- 1 Introduction
- 2 Basic Configuration
- 2.1 Location of Alfresco Configuration Files
- 2.2 Location of Extension Configuration Files
- 2.3 Alfresco Core Configuration Files
- 2.4 Configuration Changes
- 2.4.1 Global Property Overrides
- 2.4.2 Advanced Spring Configuration
- 2.5 New Installations
- 3 Automatic System Configuration Checks
- 4 Extension Samples
- 5 Issues
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".
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.
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>:
- Tomcat (see Install Tomcat6)
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.
- 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.
- Core Alfresco beans are defined here, including the importing of properties using the repository-properties bean.
- 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.
- 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.
- This determines whether Hibernate updates the database schema or just validates it.
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.
As of version 3.2, the file alfresco-global.properties can be used to override default settings for virtually all the parameters that drive Alfresco.
Please note that alfresco-global.properties is placed directly in <extensionRoot>. Older alfresco configuration files (such as custom-repository.properties) tend to be placed in <extensionRoot>/alfresco
Obtain alfresco-global.properties.sample 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.
dir.root=/srv/alfresco/data/live db.driver=oracle.jdbc.OracleDriver db.url=jdbc:oracle:thin:@<machinename>:1521:<database sid> db.name=alfresco_live hibernate.dialect=org.hibernate.dialect.OracleDialect
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>/alfresco-global.properties 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)
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.
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 alfresco-global.properties 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:
Mixing alfresco-global.properties 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 alfresco-global.properties, as described here.
- Set all common defaults for your system
- On each installation, you can add the final configuration values. For example
- -Dindex.tracking.cronExpression="0/5 * * * * ?"
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:
- JGroups Cluster (Enterprise)
- <configRoot>/alfresco/jgroups-default.xml (TCP)
- <configRoot>/classes/alfresco/jgroups-default.xml (UDP)
Advanced Spring Configuration
See also Overriding Spring Configuration.
For this example, let us assume the following directory structure:
/srv/alfresco/data/live /etc/alfresco/config/custom-config.xml /etc/alfresco/config/more-config.xml
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:
- Import custom configuration files as necessary.
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> <beans> <!-- import further configurations --> <import resource="file:/etc/alfresco/config/more-config.xml" /> </beans>
- Override any bean definitions here.
<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'> <beans> <!-- overriding the mail action to remove it as a public action --> <bean id="mail" class="org.alfresco.repo.action.executer.MailActionExecuter" parent="action-executer"> <property name="publicAction"> <value>false</value> <!-- setting to false --> </property> <property name="mailService"> <ref bean="mailService"></ref> </property> </bean> </beans>
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 alfresco-global.properties 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.
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.