Changing dotCMS Configuration Properties - Documentation topics on: configuration,configuration properties,.

Changing dotCMS Configuration Properties

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

To override the configuration properties, you must do both of the following:

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.

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 Variable References

You may include references to environment variables and system variables in your property values. These references will be replaced with the value of the appropriate environment or system variable 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 variables with any changes required for the local server.

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

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

Note that you may include multiple references and mix environment and system variable references within the same property value.


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.