OpenCms documentation
OpenCms documentation

Configuration files

OpenCms is highly configurable. You replace many Java classes with your own implementation, you can adjust, reduce and extend OpenCms' features in many respects by just by changing the configuration.

The configuration is placed in XML files on the RFS in the file ${WEBAPP_HOME}/WEB-INF/config/opencms.xml, that includes some other configuration files placed in the same folder.

We provide an overview on the different configuration files and their purposes, and explain, from a bird's eye view, when (and how) they should be altered.

We do not provide a complete overview on all available configuration options. The topic will help you to get the general directions where you could search for special configuration options.

The main configuration file. Here all configuration classes are registered.

 

The file contains all configurations somehow related to import and export, in particular:

  • module or database imports and exports
  • settings for the static export
  • settings for user csv export
  • configuration of repository view on the vfs, e.g., the samba-share.

To get an overview on all available options, consult the

The configuration of all installed modules, reaching from general module meta-information up to the explorertype and resourcetype definitions for types exposed by modules.

To get an overview on all available options, consult the

Contains the configured scheduled jobs. Jobs are typically managed via the "Scheduled jobs" app.

To get an overview on all available options, consult the

OpenCms specific search configuration, e.g., index sources, document types, ....

To get an overview on all available options, consult the

Contains the site configuration. Use the "Websites" app to change these configurations.

To get an overview on all available options, consult the

Configuration of system (installation) specific settings, e.g., the available locales and many more options. The settings that typically change from test to production environment were factored out since OpenCms 11 in the the opencms-sites.xml and opencms-scheduler.xml.

To get an overview on all available options, consult the

The file persists internal OpenCms information, as currently, for example, login messages set via the sessions app. It should not be edited manually.

The file contains settings concerning the handling of VFS resources. For example, resource loaders can be configured here, but also widgets for the content editor can be registered.

To get an overview on all available options, consult the

The file contains various configuration options related to the workplace, reaching from different handlers up to preferences.

To get an overview on all available options, consult the

OpenCms is configured via several XML files residing in the RFS under {webapp home}/WEB-INF/config/. Parts of the configuration are depending on the server your installation runs on, e.g. the site configuration, email server configuration. Adjusting it is necessary, e.g., when moving from development to production.

Before OpenCms 10, adjusting the configuration implied to replace whole files or to use your own script to manipulate the config files. Now, it is possible to apply XSL transformations on the config files. The transformations are provided via the file opencms-configuration.xslt under {webapp home}/WEB-INF/config/. The tranformations are performed on start-up and applied to all XML configuration files.

Be careful when changing configurations from inside OpenCms. The transformations will be written back to your configuration files together with your changes.

The adjusted configuration is logged at debug level. If you switch the log level to debug, the transformed configuration will be printed to the opencms.log.

More information is found in sourcecode and JavaDoc. Search for the method tranformConfiguration(..) in the class org.opencms.configuration.ConfigurationManager.

A typical XSLT file

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

    <!-- Parameter containing the current file name. This is set by OpenCms.  -->
    <xsl:param name="file" />
    
    <!-- Mandatory. The @dtd@ string is a special macro used by OpenCms to insert the correct DTD reference. -->
    <xsl:output doctype-system="@dtd@" indent="yes"  />

    <!-- 'Copy' rule used to copy everything that isn't matched by the other rules. -->
    <xsl:template match="@* | node()">
        <xsl:copy>
            <xsl:apply-templates select="@* | node()"/>
        </xsl:copy>
    </xsl:template>

    <!-- Adjust the site configuration -->
    <xsl:template match="/opencms/system/sites">
        <sites>
            <workplace-server>http://days-demo</workplace-server>
            <!-- ... other required nodes -->
        </sites>
    </xsl:template>

</xsl:stylesheet>

The XSL transformation file has always the same wrapper as above and typically it contains the copy rule, that just leaves everything untouched that is not explictly overwritten by another, more specific rule.

In the above example, we replace the site configuration. It is the typical case, that whole nodes from the configuration are replaced.