Configuration Properties

You may modify a large number of dotCMS configuration properties to customize the behavior of your system. However, no matter which properties you change, it's very important that to override through either environmental variables or system table entries. Initial system properties are defined in dotCMS configuration files, but no file changes are required (or recommended) to alter properties.

The methods outlined in this document make it much easier for you to maintain and manage your configuration changes in a single location, and help prevent overwriting your changes during later dotCMS upgrades.

Configuration File Names and Locations

The following dotCMS configuration files contain the initial property definitions:

Modifying these files directly should never be necessary. However, these can still serve as a reference.

Using Environment Variables

Setting environment variables in the environment that runs your dotCMS instance will override default dotCMS configuration properties. This 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.
  • The system table (below) is the second in the order of precedence.
  • Lastly, all file-based properties — the .properties file defaults, plugin-based extension files, etc.
  • If the same property is adjusted through an environment variable, the system table, and a properties file, the value in the environment variable will override the others.
• 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.
  • Similarly, Tomcat properties do not use the DOT_ prefix; so, for example, TOMCAT_REDIS_SESSION_ENABLED is the key for the relevant Tomcat property.
  • In general, the DOT_ prefix is intended to prevent 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
     

   • Similarly, if you're applying the variable via an orchestrator file, such as docker-compose.yml, then it might appear in the YAML as follows:

     dotcms:
     environment:
         DOT_CACHE_DEFAULT_CHAIN: 'com.dotmarketing.business.cache.provider.timedcache.TimedCacheProvider'
     

3. If your use case 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.

Using the System Table

The system table is a database table that stores key-value pairs, built to allow dynamic adjustment to configuration properties on the fly. System table entries override file-based property definitions — i.e., system defaults — but cannot override environment variables, which have the highest precedence.

The system table can be read or modified through API calls to the /api/v1/system-table path. These changes can often be implemented without restarting your dotCMS system, such as when modifying cache regions. However, properties that are only loaded on startup will still require restarting the system.

Each key in the system table is the name of a configuration property; each value, its setting. The keys may be rendered using either the DOT_ notation style used for environment variables, or the style of notation that appears in the configuration files; either one will have the same outcome.

For example, if you want to increase the contentletcache from 5,000 to 5,555, the payload of your POST call might look like this:

{
  "key": "cache.contentletcache.size",
  "value": "5555"
}

Or this:

{
  "key": "DOT_CACHE_CONTENTLETCACHE_SIZE",
  "value": "5555"
}

Whichever of these you apply, the Maintenance tool will show that the contentletcache size has been adjusted accordingly. If an entry of both key formats exist, the DOT_ style entry will take precedence.

The system table endpoints permit the classic CRUD operations: POST for create, GET for read, PUT for update, and DELETE for delete.

Fetching Entries

Fetching data from the system table involves GET calls, either with or without a path parameter.

Calling GET on /v1/system-table without a parameter will return the system table's entire dictionary as a JSON object.

curl -X 'GET' \
  'http://localhost:8082/api/v1/system-table/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $TOKEN'

Including a key as a path parameter will only fetch the value of that key, if present.

curl -X 'GET' \
  'http://localhost:8082/api/v1/system-table/cache.actionscache.size' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer $TOKEN'

Writing Entries

Writing to the table can be conducted either via POST or PUT calls that include a JSON payload containing the data to be written.

In the case of POST calls, if the key defined in the payload is already present, then this will overwrite the existing value. If the key does not exist, then it will write a new entry.

curl -X 'POST' \
  'http://localhost:8082/api/v1/system-table' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "property.name",
  "value": "1234"
}'

PUT calls look similar to POST calls, and can likewise overwrite existing values. However, PUT cannot create new entries; If the key does not already exist, it will return an error.

curl -X 'PUT' \
  'http://localhost:8082/api/v1/system-table' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "property.name",
  "value": "1234"
}'

Removing Entries

Keys can be removed from the system table through API calls using the DELETE method. Each call can remove a single entry by providing the target key as a path parameter — similar to the single-key GET endpoint.

curl -X 'DELETE' \
  'http://localhost:8082/api/v1/system-table/cache.categorybykeycache.size' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'accept: application/json'