Repository Configuration

Showing results for 
Search instead for 
Did you mean: 

Repository Configuration

0 0 15.6K

Obsolete Pages{{Obsolete}}

The official documentation is at:

Back to Server Configuration


The alfresco system configuration has been designed to be extensible and overridable.

There are two sets of spring configuration files, the default ones provided by Alfresco Alfresco configuration files and your own extension configuration files which replace or override the Alfresco provided values with your own configuration. 

This page gives details of how to override configurations without modifying any of the configuration files that are deployed by the Alfresco application.

WARNING: Modifying Alfresco-maintained configuration files is is not recommended.   Your changes will be overwritten when upgrading alfresco and it can be confusing to track down problems.    The simple rule of thumb is 'Do not edit anything below the alfresco WEB-INF folder'.

Basic Configuration

Location of Alfresco Configuration Files

The core Alfresco configuration files are present in the alfresco war file and get expanded out once the server starts.   These files provide the 'default' configuration for alfresco. 

This location, referred to as <configRoot>, varies depending on the environment that Alfresco runs in.

  • JBoss

  • Tomcat

Location of Extension Configuration Files

Your customized configuration files can be created prior to server startup and can be added to the following locations, referred to as <extensionRoot>:

  • JBoss


Sample files can be downloaded directly from Subversion.

Alfresco Core Configuration Files

The <configRoot> folder, and especially the <configRoot>/classes/alfresco folder contains the core, Alfresco-maintained, configuration files. 

If you are new to Alfresco then take a brief look at the following files,
which form the core of the Alfresco application configuration. 
Once again: There should be no need to modify these directly.

  • <configRoot>/classes/alfresco/application-context.xml
This is the starting point of the Spring configurations.
This file only performs imports, including a wildcard import of all classpath*:alfresco/extension/*-context.xml files.

  • <configRoot>/classes/alfresco/core-services-context.xml
Core Alfresco beans are defined here, including the importing of properties using the repository-properties bean.

  • <configRoot>/classes/alfresco/
This properties file, imported by the repository-properties bean, defines some of the core system properties, including:
This is the location where the binary content and Lucene indexes are stored.  It is relative by default, but should be pointed to a permanent, backed-up location for permanent data storage.

These are the core database connection properties.

  • <configRoot>/classes/alfresco/domain/
This properties file, imported by the hibernateConfigProperties bean, defines Hibernate core system properties.  Descriptions can be found in the Hibernate documentation.
This alters the SQL dialect that Hibernate uses when issuing queries and updates to the database.  Normally this is the only Hibernate property that will need changing, depending on the database you are running against.  (Hibernate SQL Dialects)
This determines whether Hibernate updates the database schema or just validates it.
  • update    - Checks and updates the database schema as appropriate
  • validate  - Checks the database schema and fails if it is not compliant.

Configuration Changes

Global Property Overrides

In order for you to be able to tailor your Alfresco installation to suit its deployment environment, Alfresco supports a number of global properties with which you can specify the parameters of your environment. There are several ways to control these properties, as you will see below. (V3.2+)

As of version 3.2, the file can be used to override default settings for virtually all the parameters that drive Alfresco.

Please note that is placed directly in <extensionRoot>.   Older alfresco configuration files (such as tend to be placed in <extensionRoot>/alfresco

Obtain and copy it to your application server's global classpath without the .sample extension, described here as <extensionRoot>. If using Tomcat 6, be sure to follow the instructions in Install Tomcat6 -- in particular, to set the shared.loader Catalina property. Now uncomment and edit the settings in the file to match your environment.

  • Choose a root location for the storage of content binaries and index files (dir.root).
  • Adjust properties here to change the database connection details.
  • Pay attention to the choice of JDBC driver used with each connection type.
  • Optionally, set the Hibernate dialect for your database (see Hibernate Dialects). If you don't specify a dialect, Hibernate will attempt to detect the dialect of your database automatically from the JDBC connection.

For example:

db.url=jdbc:oracle:thin:@<machinename>:1521:<database sid>

precedence of property files (V3.2+)

There are several files that can contain property values, some of which are there for backwards compatibility with older releases of Alfresco.  In general the advice is simple, put your custom configuration values in <extensionRoot>/ unless the configuration applies to a specific instance of a subsystem or module.

However If you have conflicting values in different property files, which one will win?   

  • Files in order of priority, most important first.
    • JMX changes persisted in the database (Enterprise Only)
    • <extensionRoot>/alfresco/extension/subsystems/<category>/<typeName>/*.properties
    • <extensionRoot>/alfresco/subsystems/<category>/default/*.properties
    • <extensionRoot>/
    • <extensionRoot>/alfresco/module/*/
    • <extensionRoot>/alfresco/

And last and lowest in priority are the alfresco supplied defaults configured within the alfresco web application.   However it is never good practice to modify those files with custom configuration.

Spring Configuration

Refer to Configuring Older Alfresco Releases.

Command Line Configuration (V2.1-A, V3.1+)

As of version V2.1-A and V3.1, the beans that load the Repository and Hibernate properties will give preferential treatment to any JVM-set properties. So rather than using or the older mechanisms documented above, you may set properties directly as arguments to the JVM.

To set a property directly on the JVM, set the system properties like this:


set JAVA_OPTS=-Ddir.root=e:/alfresco/data


export JAVA_OPTS='-Ddir.root=/srv/alfresco/data'

Mixing and System Property Setting

The custom sample files have been updated with the releases to reflect these changes.  You can use a combination of the two approaches.  For instance if you wish to distribute a system that has a core set of properties overridden but need to customize the last few for each installation, the follow this process:

  • Activate the sample, as described here.
  • Set all common defaults for your system
  • On each installation, you can add the final configuration values.  For example
    • -Ddb.username=alfresco
    • -Ddb.password=alfresco
    • -Dhibernate.dialect=org.alfresco.repo.domain.hibernate.dialect.AlfrescoOracle9Dialect
    • -Dhibernate.default_schema=ALFRESCO_DEV
    • -Dindex.tracking.cronExpression='0/5 * * * * ?'
    • -Dindex.recovery.mode=AUTO
What Can Be Set?

Examine the following properties files for a list of properties that are typically modified and to see the default values.  It is not the full list, but most of the useful properties are covered:

  • Repository:
    • <configRoot>/classes/alfresco/
      • dir.root
      • db.username
      • db.password
      • db.pool.initial
      • db.pool.max
      • db.schema.update
      • db.driver
      • db.url
      • index.tracking.cronExpression
      • index.recovery.mode
    • <configRoot>/classes/alfresco/
      • hibernate.dialect
      • hibernate.query.substitutions
      • hibernate.jdbc.use_get_generated_keys
      • hibernate.default_schema
  • JGroups Cluster (Enterprise)
    • <configRoot>/classes/alfresco/
      • alfresco.jgroups.configLocation
      • alfresco.jgroups.defaultProtocol
    • <configRoot>/alfresco/jgroups-default.xml (TCP)
      • alfresco.tcp.start_port
      • alfresco.tcp.initial_hosts
      • alfresco.tcp.port_range
    • <configRoot>/classes/alfresco/jgroups-default.xml (UDP)
      • alfresco.udp.mcast_addr
      • alfresco.udp.mcast_port
      • alfresco.udp.ip_ttl

Advanced Spring Configuration

See also Overriding Spring Configuration.

For this example, let us assume the following directory structure:


Alfresco's configuration is driven by: <configRoot>/classes/alfresco/application-context.xml (after version 1.1.2).
While this file includes many other  Spring configuration files explicitly, it contains a 'wildcard' import directive that can import many others:

   <import resource='classpath*:alfresco/extension/*-context.xml' />

This import directive ensures that all locations on the classpath are searched for extension context definitions.   Note:  the Spring classpath*: prefix means 'load all files of the same name found on the classpath, not just the first one found').  Thus, it is possible to override Spring-imported beans within the following configuration files, without having to modify <configRoot>/classes/alfresco/application-context.xml.

Here are some configuration files used by Alfresco:

  • <extensionRoot>/alfresco/extension/custom-services-context.xml
Import custom configuration files as necessary.


    <import resource='file:/etc/alfresco/config/more-config.xml' />


  • /etc/alfresco/config/more-config.xml
Override any bean definitions here.


    <bean id='mail' class='org.alfresco.repo.action.executer.MailActionExecuter' parent='action-executer'>
        <property name='publicAction'>
        <property name='mailService'>
            <ref bean='mailService'></ref>


New Installations

For Alfresco releases prior to version 3.2, see Configuring Older Alfresco Releases.

Before running the server for the first time, it is highly recommended that the database connection details and alfresco data folder locations get checked and set according to the environment in which the server is running.  By default, the server will create a data folder for storing content binaries and indexes at a location relative to the caller's location when the server is started.  This is appropriate for quick previews and tests, but should be changed when running a server that will be storing long-lived data.

This can be achieved quite easily by setting up an file, as described here.

Once this is done, and all other instructions in the appropriate README files have been followed, the server can be started.  The configuration overrides will ensure that the server immediately directs data to the appropriate locations.

If you keep getting the 'Ensure that the 'dir.root' property is pointing to the correct data location' error, it means there is something wrong with that data folder or it is inconsistent with the database. In that case you may try deleting all the files in the data folder and re-creating the database, before restarting the server.

Automatic System Configuration Checks

The server performs a configuration check to ensure that the content, indexes and database are properly configured.  The configurationChecker can be found in <alfresco.war>/WEB-INF/classes/alfresco/bootstrap-context.xml.  Usually, nothing will need to be changed, but the default behaviour is to prevent the system from starting up if the content-indexes-database configuration is incorrect.
To start the server regardless of errors, set system.bootstrap.config_check.strict=false.  Note that index checking is ignored if FULL index recovery has been activated.

Extension Samples

Note that over time, these are being replaced by Subsystems.

  • The project Extension Samples (available via SVN) contains further examples of extending configurations in various ways.
  • The JBoss and Tomcat bundles ship with a set of template *.xml.sample files in the <extensionRoot> locations.


  • The server processes need to have permissions to view the configuration extensions
  • When upgrading, double check any overridden beans for any pertinent changes that might have occured within the Alfresco-maintained set
  • In live systems, we advise running against a copy of the live data first.
  • If you use non-Alfresco classes that import classes found in the alfresco.war, then you will have to drop your jars into the <TOMCAT_HOME>/webapps/alfresco/WEB-INF/lib in Tomcat.  The classloader will not allow you to reference classes in the web-app from the <TOMCAT_HOME>/shared/lib folder.