Changing 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 the dotCMS configuration plugin (com.dotcms.config, included with the dotCMS distribution) 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.

The configuration plugin allows you to override individual dotCMS properties for the most commonly edited configuration files through the use of configuration plugin extension files.

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:


Note: If you wish to modify a configuration file not shown in this list, please override it using a ROOT folder plugin.

Overriding Configuration Properties with Environment Variables

You can set environment variables on the server that runs your dotCMS instance, to set and override dotCMS configuration properties. This is of special importance when deploying dotCMS using Docker, as it allows you to set dotCMS configuration properties in the standard dotCMS Docker images without modifying any files in the dotCMS distribution. 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.
  • All environment variables used to set dotCMS configuration properties must begin with DOT_.
    • This 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.
  2. Update your server scripts to set the environment variable to the new value.
    • Example:
  3. Restart your dotCMS instance.

Overriding Configuration Properties via plugin

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


  • 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.
  2. Deploy your dotCMS plugins.
    • From the root of your dotCMS installation, run the following command:
  3. Restart dotCMS.

The changes made in your properties extension files will now override the identically named properties in your and 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.
  2. Undeploy your dotCMS plugins.
    • From the root of your dotCMS installation, run the following command:
  3. Restart dotCMS.

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:

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


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


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


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


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.