Configuration Properties documentation for the dotCMS Content Management System

You may modify a large number of dotCMS configuration properties to customize the behavior of your system. However, no matter which configuration properties you change it's very important that you override them using environmental variables rather than changing them directly in the dotCMS configuration files. This makes it much easier for you to maintain and manage your configuration changes in a single location, and helps prevent overwriting of your changes during later dotCMS upgrades.

Configuration File Names and Locations

The following dotCMS configuration files can be overridden with configuration plugin extension files:

Configuration FilePurpose
dotmarketing-config.propertiesThe main dotCMS configuration properties.
dotcms-config-cluster.propertiesProperties related to cluster configuration.
portal.propertiesSecurity and user authentication configuration.

All of these files are stored in the following directory in your dotCMS installation:

/dotserver/tomcat-X.x/webapps/ROOT/WEB-INF/classes/

Overriding Configuration Properties with Environment Variables

You can set environment variables in the environment that runs your dotCMS instance which will override default dotCMS configuration properties. Using environmental variables to set configuration is important when deploying dotCMS using Docker or if running dotCMS as a downloaded binary, as it allows you to set dotCMS configuration properties without modifying any files in the dotCMS distribution or docker image. It is also a very clean way to set configuration properties that persists through upgrades.

Important Notes:

  • Properties set through environment variables will take precedence over all other configuration property settings.
    • If you set a property via both a Properties Extension File and through an environment variable, the value in the environment variable will override the value in the file.
  • Environment variables used to set dotCMS configuration properties must begin with DOT_.
    • Properties set through dotCMS that start with PROVIDER_DB or PROVIDER_ELASTICSEARCH do not need the DOT_ prefix because they are setting properties in systems outside of dotCMS, Postgres and ElasticSearch.
    • The DOT_ prefix prevents variable collisions.

To set a configuration property using an environment variable:

  1. Identify the environment variable name needed to override the configuration property.

    • Start with the configuration property name.
      • Example: cache.default.chain
    • Convert the name to all uppercase.
      • Example: CACHE.DEFAULT.CHAIN
    • Replace any periods (dots) in the property name with underscores.
      • Example: CACHE_DEFAULT_CHAIN
    • Add DOT_ to the beginning of the name.
      • Example: DOT_CACHE_DEFAULT_CHAIN
  2. Update your server scripts to set the environment variable to the new value.

    • Example: DOT_CACHE_DEFAULT_CHAIN=com.dotmarketing.business.cache.provider.timedcache.TimedCacheProvider
  3. If you are using the binary distribution, we recommend creating a setenv.sh file that holds all your configurations. To do this, create the file $TOMCAT_HOME/bin/setenv.sh and in it export your environmental variables, e.g.

    export DOT_COOKIES_HTTP_ONLY=true
    export DOT_CACHE_DEFAULT_CHAIN=com.dotmarketing.business.cache.provider.timedcache.TimedCacheProvider
    

    On startup, Tomcat will automatically read the setevn.sh file and include the configurations in your dotCMS environment.

  4. You will need to restart your dotCMS instance or container in order for any environmental varibles to be read.

Overriding Configuration Properties via plugin

Deprecated

Using Properties Extension Files

To override the configuration properties using Properties Extension Files, you must do both of the following:

  1. Edit the properties extension file(s)
  2. Deploy your dotCMS plugins

1. Edit the Properties Extension File

The properties extension files are found in the plugins/com.dotcms.config/conf directory of your dotCMS installation. The name of each extension file is the same as the name of the source properties file, with -ext added to the file name (before the file extension), so the extension file to edit depends on the types of properties you wish to change.

To override a configuration property via a static configuration plugin, perform the following steps:

  1. Edit the appropriate extension file:
    • dotmarketing-config-ext.properties
    • dotcms-config-cluster-ext.properties
    • portal-ext.properties
  2. Copy the property that you would like to change from the source file (in the $DOTCMSHOME/dotserver/tomcat-X.x.xx/webapps/ROOT/WEB-INF/classes folder):
    • dotmarketing-config.properties
    • dotcms-config-cluster-ext.properties
    • portal.properties
  3. Paste the property into the extension file.
  4. In the extension file (only), change the property setting to the new value.
  5. Save the extension file.

Important:

  • The property names are both case sensitive and sensitive to spaces.
    • So you must make sure the property name (everything before the equals sign) in the properties extension file exactly matches the property name in the base properties file.
    • Case mismatches or extra spaces will prevent the new property value from being used.

2. Deploy dotCMS Plugins

After you have made all configuration changes, you must deploy your dotCMS plugins:

  1. Shut down dotCMS.
    ./bin/shutdown.sh
    
  2. Deploy your dotCMS plugins.
    • From the root of your dotCMS installation, run the following command:
      ./bin/deploy-plugins.sh
      
  3. Restart dotCMS.
    ./bin/startup.sh
    

The changes made in your properties extension files will now override the identically named properties in your dotmarketing-config.properties and dotcms-config-cluster.properties source files. When you upgrade dotCMS, you need only copy your plugins folder and re-deploy your plugins to restore your modified configuration.

Removing Property Changes

To remove the property changes and restore dotCMS config properies to their original settings, do the following:

  1. Shut down dotCMS.
    ./bin/shutdown.sh
    
  2. Undeploy your dotCMS plugins.
    • From the root of your dotCMS installation, run the following command:
      ./bin/undeploy-plugins.sh
      
  3. Restart dotCMS.
    ./bin/startup.sh
    

Property File Values

The property files consist of a assignments with a property on the left and a value on the right, separated by an equal sign. Property names may not contain spaces, but property values may contain spaces (depending on the expected value of the property).

Environment and System Property References

You may include references to environment variables and system properties in your property values. These references will be replaced with the value of the appropriate environment or Java system property anywhere within the property value.

Using references allows you to create a common set of properties files that can be used on different servers and in different environments without modification; you may instead modify the behavior of each server or environment by setting and referencing the appropriate environment or system properties with any changes required for the local server.

You may use the following format to reference environment and system properties, where VARIABLE represents the name of the environment or system property to be included:

ReferenceFormat
Environment Variable{env:VARIABLE}
Java System Property{sys:VARIABLE}

Note:

  • You may include multiple references and mix environment and system property references within the same property value.
  • You may view the values of your server's environment variables and system properties in the System Info tab of the System -> Maintenance Tool.

Example

For example, the following sets the ASSET_REAL_PATH property based on the value of an environment variable named SERVER:

ASSET_REAL_PATH=/mnt/remote/{env:SERVER}/cluster1/assets

Reloading Property Files

By default, dotCMS monitors your property files and reloads them automatically (typically within a few seconds) any time they are changed. This will happen both if you make changes to your properties extension file and then deploy the configuration plugin (recommended) or if you directly edit the properties file.

If you wish to manually force a properties file to reload, you may “touch” the properties file, updating the modified timestamp on the file, which will cause dotCMS to reload the properties.

Disabling Watcher Mode

In order to reload the properties file quickly after any change, dotCMS continually monitors each of the properties files for changes. If you wish to disable continual monitoring of the properties files, you may disable the watcher mode by adding the following property to the dotmarketing-config.properties file:

dotcms.usewatchermode=false.

When you disable watcher mode, the properties files will be checked for changes every five minutes, meaning that any changes you make to the properties files may take up to 5 minutes to take effect.