Configuration Properties

Last Updated: Mar 29, 2022
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 environmental variables:

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.

On this page