Hyland Connect

resplin · ‎06-05-2015

The official documentation is at: http://docs.alfresco.com

Configuration 3.2
Back to Server Configuration

Introduction

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

<JBOSS_HOME>/server/default/tmp/deploy/tmp*alfresco-exp.war/WEB-INF

Tomcat

<TOMCAT_HOME>/webapps/alfresco/WEB-INF

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

<JBOSS_HOME>/server/default/conf/

Tomcat (see Install Tomcat6)

<TOMCAT_HOME>/shared/classes/

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/repository.properties

This properties file, imported by the repository-properties bean, defines some of the core system properties, including:

dir.root

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.

db.*

These are the core database connection properties.

<configRoot>/classes/alfresco/domain/hibernate-cfg.properties

This properties file, imported by the hibernateConfigProperties bean, defines Hibernate core system properties. Descriptions can be found in the Hibernate documentation.

hibernate.dialect

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)

hibernate.hbm2ddl.auto

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.

alfresco-global.properties (V3.2+)

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.

For example:


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)
- <extensionRoot>/alfresco/extension/subsystems/<category>/<typeName>/*.properties
- <extensionRoot>/alfresco/subsystems/<category>/default/*.properties
- <extensionRoot>/alfresco-global.properties
- <extensionRoot>/alfresco/module/*/alfresco-global.properties
- <extensionRoot>/alfresco/repository.properties

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 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:

Windows:


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

Linux:


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

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
- -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
- -Dalfresco.cluster.name=ALFRESCO_DEV

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/repository.properties
  - 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
  - alfresco.cluster.name
- <configRoot>/classes/alfresco/hibernate-cfg.properties
  - hibernate.dialect
  - hibernate.query.substitutions
  - hibernate.jdbc.use_get_generated_keys
  - hibernate.default_schema
JGroups Cluster (Enterprise)
- <configRoot>/classes/alfresco/repository.properties
  - 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:


/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:

<extensionRoot>/alfresco/extension/custom-services-context.xml

Import custom configuration files as necessary.


<beans>

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

</beans>

/etc/alfresco/config/more-config.xml

Override any bean definitions here.


<beans>

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

</beans>

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 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.

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.

Issues

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.