Repository Configuration

From AlfrescoWiki

1 Introduction
2 Basic Configuration
3 Command Line Configuration (V2.1.5, V2.1-A, V2.2.1)
4 Automatic System Configuration Checks
5 Extension Samples
6 Issues

[edit] Introduction

From version 1.2 of the repository, the system configuration has been designed to be extensible and overridable. 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 risky and, as of version 1.2, not recommended.

[edit] Basic Configuration

[edit] Location of Alfresco Configuration Files

The core Alfresco configuration files are present in the application war file and get expanded out once the server starts. 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/classes

Tomcat

<TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes

[edit] Location of Extension Configuration Files

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

<TOMCAT_HOME>/shared/classes/

[edit] Core Configuration Files

The <configRoot> folder, and especially the <configRoot>/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>/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>/alfresco/core-services-context.xml

Core Alfresco beans are defined here, including the importing of properties using the repository-properties bean.

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

[edit] Configuration Changes

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

/srv/alfresco/data/live
/srv/alfresco/data/test
/etc/alfresco/config/test.repository.properties
/etc/alfresco/config/live.repository.properties
/etc/alfresco/config/hibernate.properties
/etc/alfresco/config/custom-config.xml

Alfresco's configuration is driven by: <configRoot>/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>/alfresco/application-context.xml.

Here are some configuration files used by Alfresco:

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

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>

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

Override any bean definitions here, including the basic repository properties.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>

<beans>

    <!-- overriding to point to custom properties -->
    <bean id="repository-properties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="ignoreUnresolvablePlaceholders">
            <value>true</value>
        </property>
        <property name="locations">
            <list>
                <value>classpath:alfresco/repository.properties</value>
                <value>classpath:alfresco/version.properties</value>
                <value>classpath:alfresco/domain/transaction.properties</value>

                <value>file:/etc/alfresco/config/live.repository.properties</value>  <!-- override core properties -->
            </list>
        </property>
    </bean>

    <!-- override Hibernate properties -->
    <bean id="hibernateConfigProperties" class="org.springframework.beans.factory.config.PropertiesFactoryBean">
        <property name="locations">
            <list>
                <value>classpath:alfresco/domain/hibernate-cfg.properties</value>
                <value>file:/etc/alfresco/config/hibernate.properties</value>
            </list>
        </property>
    </bean>

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

/etc/alfresco/config/live.repository.properties

This file need only contain modifications

dir.root=/srv/alfresco/data/live
db.driver=oracle.jdbc.OracleDriver
db.url=jdbc:oracle:thin:@<machinename>:1521:<database sid>
db.name=alfresco_live

/etc/alfresco/config/hibernate.properties

This file need only contain modifications

hibernate.dialect=org.hibernate.dialect.OracleDialect

The server initialization ensures that all configuration files are located and the bean definitions imported. This includes the extensions located externally on the classpath. By overrding the repository-properties bean defined in <configRoot>/alfresco/core-services-context.xml and importing an additional properties file, it is possible to override individual server properties.

[edit] New Installations

This is useful information for upgrades as well.

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.

Locate the distribution's extension configuration files and samples (here) and remove the .sample extensions:

<extensionRoot>/alfresco/extension/custom-repository-context.xml.sample
- This ensures that the properties overrides from the files below are pulled into the server.
<extensionRoot>/alfresco/extension/custom-repository.properties.sample
- Choose a root location for the storage of content binaries and index files.
- Adjust properties here to change the database connection details.
- Pay attention to the choice of JDBC driver used with each connection type.
<extensionRoot>/alfresco/extension/custom-hibernate-dialect.properties.sample
- Choose a Hibernate schema most appropriate to your database (Hibernate Dialects).

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.

[edit] Command Line Configuration (V2.1.5, V2.1-A, V2.2.1)

[edit] What has changed?

As of version 2.1.3 and V2.1-A, the beans that load the Repository and Hibernate properties will give preferential treatment to any JVM-set properties.

<configRoot>/alfresco/core-services-context.xml:

    <bean id="repository-properties" 
          class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="ignoreUnresolvablePlaceholders">
            <value>true</value>
        </property>
        <property name="locations">
            <list>
                <value>classpath:alfresco/repository.properties</value>
                <value>classpath:alfresco/version.properties</value>
                <value>classpath:alfresco/domain/transaction.properties</value>
                <value>classpath:alfresco/jndi.properties</value>
            </list>
        </property>
        <property name="systemPropertiesModeName">
            <value>SYSTEM_PROPERTIES_MODE_OVERRIDE</value>
        </property>
    </bean>

<configRoot>/alfresco/hibernate-context.xml:

    <bean id="hibernateConfigProperties" class="org.alfresco.config.SystemPropertiesFactoryBean">
        <property name="systemProperties">
            <list>
                <value>hibernate.dialect</value>
                <value>hibernate.query.substitutions</value>
                <value>hibernate.jdbc.use_get_generated_keys</value>
                <value>hibernate.default_schema</value>
            </list>
        </property>
        <property name="locations">
            <list>
                <value>classpath:alfresco/domain/hibernate-cfg.properties</value>
            </list>
        </property>
    </bean>

[edit] Setting Properties

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

[edit] Mixing Bean Overrides 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 samples (remove the sample extensions):
- <extension>/alfresco/extension/custom-repository-context.xml.sample
- <extension>/alfresco/extension/custom-repository.properties.sample
- <extension>/alfresco/extension/custom-hibernate-dialect.properties.sample
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.hibernate.dialect.Oracle9Dialect
- -Dhibernate.default_schema=ALFRESCO_DEV
- -Dindex.tracking.cronExpression="0/5 * * * * ?"
- -Dindex.recovery.mode=AUTO
- -Dalfresco.cluster.name=ALFRESCO_DEV

[edit] 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>/alfresco/repository.properties
- <extension>/alfresco/extension/custom-repository.properties.sample
  - 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>/alfresco/hibernate-cfg.properties
- <extension>/alfresco/extension/custom-hibernate-dialect.properties.sample
  - hibernate.dialect
  - hibernate.query.substitutions
  - hibernate.jdbc.use_get_generated_keys
  - hibernate.default_schema
JGroups Cluster
- <configRoot>/alfresco/jgroups-default.xml (TCP)
  - alfresco.tcp.start_port
  - alfresco.tcp.initial_hosts
  - alfresco.tcp.port_range
- <configRoot>/alfresco/jgroups-default.xml (UDP)
  - alfresco.udp.mcast_addr
  - alfresco.udp.mcast_port
  - alfresco.udp.ip_ttl
File Servers
- <configRoot>/alfresco/file-servers.properties
  - filesystem.name
  - cifs.enabled
  - cifs.localname=
  - cifs.domain=
  - cifs.broadcast
  - ftp.enabled
  - nfs.enabled

[edit] 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.

[edit] Extension Samples

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

[edit] Issues

Before version 1.2, the configuration modifications will have been made directly against Alfresco-maintained files. Make a complete copy of the configuration folders to ensure that no settings are lost when upgrading.
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.

Retrieved from "http://wiki.alfresco.com/wiki/Repository_Configuration"

Category: Configuration

Repository Configuration

From AlfrescoWiki

Contents

[edit] Introduction

[edit] Basic Configuration

[edit] Location of Alfresco Configuration Files

[edit] Location of Extension Configuration Files

[edit] Core Configuration Files

[edit] Configuration Changes

[edit] New Installations

[edit] Command Line Configuration (V2.1.5, V2.1-A, V2.2.1)

[edit] What has changed?

[edit] Setting Properties

[edit] Mixing Bean Overrides and System Property Setting

[edit] What Can Be Set?

[edit] Automatic System Configuration Checks

[edit] Extension Samples

[edit] Issues

Views

Personal tools

Navigation

Documentation

Download and go

Support

Participate

Community

Alfresco Cookbooks

Search

Toolbox