Developer Runtime Configuration

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at:

Back to Developer Guide

See also: SVN Development Environment

Setting Environment Variables

See development environment notes.

Configuring Repository Location

One of the first things you should do is point dir.root to some concrete and permanent location. Otherwise you will start getting alf_data directories scattered around depending on where you run tests from in Eclipse or otherwise.  This creates fatal issues as the Lucene indexes, content store and database get out of synch.  On UNIX this is particularly troublesome, because most developers 'live in their shells', and are accustomed to being able to run applications from anywhere.

For older Alfresco releases prior to version 3.2, please refer to Configuring Older Alfresco Releases for instructions on how to override the dir.root property.

To set this up nicely for a current build, you should add a file:

to the root of your application server global classpath. For example, on Tomcat installations, prepared as per Install Tomcat6, you would create the file




This will allow you to use the same set of customizations regardless of which Alfresco source code branch you're working on.

An example file containing examples of dir.root and other useful settings can be found in the source tree here. Don't forget to uncomment and edit those settings applicable to your environment. And remember that on MS Windows, if you use the backslash character, it must be escaped in properties files.  The '/' character works as on all platforms including windows.  For example:


Read the section on Repository Configuration for further details.

Sample Global Properties File

A minimum properties file(on Mac OS X) would be like:


## External locations
# Point your locations correctly, otherwise errors will be raised at startup

## MySQL connection
# UTF-8 connection support
# Also don't forget to correctly set database encoding at database creation
# or default-character-set in my.cnf/my.ini

Configuring Tomcat

Please be aware of the additional requirements for configuring Tomcat 6, documented in Install Tomcat6.

On UNIX/Linux/Mac, within there's a line that looks like this:

# ----- Execute The Requested Command -----------------------------------------

Just prior to that line, add the following to avoid JVM/Hibernate problems:

#  The -server   flag avoids problems on Linux and Mac.
#  The -Xmx1024M flag gives the JVM ample memory.
if ! '${CATALINA_OPTS}' =~ '-server'; then

if ! '${CATALINA_OPTS}' =~ '-Xmx'; then

After starting Tomcat, you can verify that the -server and -Xmx1024M flags are set by issuing the command:

ps auxw | grep tomcat

If you find that your system is running the CPU at 100% and Tomcat seems to be unresponsive, you will need to kill the process and add the following lines to the script, just below the lines described in the previous paragraph.

if ! PermSize'; then

After making that change you may need to clear out the alf_data directory and recreate the alfresco database before starting Tomcat again.

If you encounter java.lang.OutOfMemoryError: PermGen space, you will need to add the following lines.

if ! MaxPermSize'; then

Configuring Log4J

Because developers must sometimes remove and redeploy an alfresco.war file repeatedly, is it sometimes useful to be able to maintain a file outside of the webapp. This allows for changing log4j settings without touching the 'shipping product', or any of a customer's local settings. Your optional file should be in some alfresco/extension directory within the server's classpath, and outside the webapp itself (so you don't accidentally delete it). The file augments/overrides all others. For example:


See also: Developing an Alfresco Module

The logging levels for the the portal are set in a Log4J configuration file found at
JBOSS_HOME\server\default\conf\log4j.xml.  Some details on the types of configurations that are possible can be found in Log4J Configuration.

The log4j settings, when running in Tomcat, can be found in the projects\core\source\java folder.

Configuring OpenOffice

Install OpenOffice 1.1.4 (or 2.0), run it once to go through registration then disable the QuickStart. Then start OpenOffice with:

..\OpenOffice.org1.1.5\program\soffice '-accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager' -nologo -headless

Registering OpenOffice

Going through registration is necessary to be able to start OpenOffice as a server and you need a GUI to do so.

If registering OpenOffice isn't so easy as it looks (because you're in some command line interface without GUI support) you could disable the registering setting as mentioned in the OpenOffice project documentation. This can be customised or disabled by setting the (Common/Help/Registration/) URL value to an empty string.

If you look at C:\Program Files\ 2.0\share\registry\data\org\openoffice\Office\Common.xcu or
/usr/lib/openoffice/share/registry/data/org/openoffice/Office/Common.xcu you'll see:

<oor:component-data oor:name='Common' oor:package='org.openoffice.Office'
    <node oor:name='Help'>
        <node oor:name='Registration'>
            <prop oor:name='URL'>