Docker Configuration Options

Last Updated: May 11, 2022
documentation for the dotCMS Content Management System

dotCMS Docker Image

dotCMS provides the a Docker image which should be used to run dotCMS in the orchestrator of your choice. The image is designed to configured via environmental variables and is easy to use while still being extremly configurable. Running dotCMS in a container is the recommended way to run dotCMS.

TL;DR Configuration Example:

    "JAVA_OPTS_MEMORY": '-Xmx4g'
    "DB_BASE_URL": "jdbc:postgresql://"
    "DB_USERNAME": 'dotcmsdbuser'
    "DB_PASSWORD": 'password'
    "DOT_ES_AUTH_BASIC_USER": 'esadmin'
    "DOT_ES_AUTH_BASIC_PASSWORD": 'espassword'
    - /volumes/dotcms-share:/data/shared

Docker Configuration:

This dotCMS image is capable of being configured to run against a varity of other containers and/or external services depending on configuration. Because most everything is configurable, you should not have to create your own docker container in order to run the dotCMS platform.

Note: The file is a reference of different configuration variables and their default values.

Java/JVM Configuration

VaribleDefault ValueDescription
JAVA_OPTS_BASEsee fileThese are the base java options passed to the jvm when started. The default should suffice for most installations.
JAVA_OPTS_AGENTsee fileThis is the java agent used attached to the JVM. The default should suffice for most installations.
JAVA_OPTS_MEMORY-Xmx1GJava heap size used for Tomcat JVM. The default is intended for demonstration purposes only. For production environments, use -Xmx4G or greater.
CMS_JAVA_OPTSemptyArguements added here are added last in the jvm arguments and will override anything set before it.

Tomcat Configuration

VaribleDefault ValueDescription
CMS_CONNECTOR_THREADS600Maximum number of connector threads to be shared across all Tomcat connectors.
CMS_COMPRESSIONonEnables/Disables GZIP compression in tomcat
CMS_COMPRESSIBLEMIMETYPEsee fileEnables/Disables GZIP compression for specific content types. The default should suffice for most installations.
CMS_ACCESSLOG_PATTERNsee fileThe access log pattern used by tomcat. The default should suffice for most installations.
CMS_REMOTEIP_REMOTEIPHEADERx-forwarded-forThe header tomcat should use when resolving a remote server ip address.
CMS_REMOTEIP_INTERNALPROXIESsee fileThe list of trusted proxies. If the remote ip address does not match these, the CMS_REMOTEIP_REMOTEIPHEADER will not be used. The default should suffice for most installations.

Database Configuration

The following options allow you to specify how dotCMS should connect to the database and should be set for every dotCMS installation.

VaribleDefault ValueDescription
DB_BASE_URLjdbc:postgresql:// URL to connect to the database.
DB_USERNAMEdotcmsdbuserUsername used to connect to the database server.
  • Must match the name of a valid database user on the database server.
DB_PASSWORDpasswordPassword used to connect to the database server.
  • Must match the password for the specified DB_USERNAME on the database server.

Database Connection Pool Configuration (Optional)

The following options are optional and allow you to tweek the database connection pool to your liking. The defaults should suffice in most situations.

VaribleDefault ValueDescription
DB_DRIVERorg.postgresql.DriverThe type of database used.
Possible values are:
  • org.postgresql.Driver (for PostgreSQL)
  • (for Microsoft SQLServer)
DB_MAX_WAIT180000Maximum lifetime (ms) of a connection in the pool.
DB_MAX_TOTAL200Maximum number of database connections permitted to the DB server.
DB_MIN_IDLE10Maximum amount of time (in seconds) that a connection is allowed to sit idle in the pool.
DB_VALIDATION_QUERY_empty_SQL query to be executed to test the validity of connections.
DB_LEAK_DETECTION_THRESHOLD300000Amount of time that a connection can be out of the pool before a message is logged indicating a possible connection leak.
DB_DEFAULT_TRANSACTION_ISOLATION_empty_Default transaction isolation level.

ElasticSearch Configuration

VaribleDefault ValueDescription
DOT_ES_ENDPOINTS comma separated list of elasticsearch endpoints/servers that dotCMS will connect to. dotCMS will load balance between the endpoints in this list.
DOT_ES_AUTH_TYPEBASICEither BASIC or JWT. Setting this to BASIC means you need to provide a username ES_AUTH_BASIC_USER and password ES_AUTH_BASIC_PASSWORD. Setting this to JWT means you need to provide a valid token ES_AUTH_JWT_TOKEN to authenticate.
DOT_ES_AUTH_BASIC_USERadminThe username to use for BASIC auth of your elasticsearch servers
DOT_ES_AUTH_BASIC_PASSWORDadminThe password to use for BASIC auth of your elasticsearch servers
DOT_ES_AUTH_JWT_TOKEN_empty_Token to use for JWT auth of your elasticsearch servers

dotCMS Configuration - DOT notation

dotCMS allows you to override any config option in the file or the files by setting environmental variables for your docker container.

To set a dotCMS configuration property using an environment variable, you need to first convert it to use the DOT notation, or the format dotCMS uses for ENV variables. Assume you want to update the dotCMS config property cache.default.chain:

  • Start with the configuration property name that you want to override.
    • Example: cache.default.chain
  • Then convert the name to all uppercase.
  • Then replace any periods (dots) in the property name with underscores.
  • Finally add DOT_ to the beginning of the name.

You can then pass this new variable into the dotCMS docker image and it will override what is in the .properties files, e.g.: docker run -e ""

See this documentation for more information regarding the proper format for overridding the dotcms config variables.

Debugging dotCMS in Docker

To debug dotCMS running in a docker container, you will need to remote attach your debugger to the java process running in the container. To do this, you will need to add the following to the CMS_JAVA_OPTS property.

"CMS_JAVA_OPTS": ' -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000'

and then make sure that port 8000 is mapped and externally available, e.g.:

        - “8000:8000”

You should then be able to attach to the debugger remotely.

Mounting Shared Folder

The dotCMS docker image only requires a single volume to persist data across restarts and a cluster. This is the /data/shared folder in the dotCMS docker image.

Path DescriptionExampleNotes
Shared folder (includes /assets /felix)[localpath]/data/shared:/data/sharedthis folder should be shared across all nodes in a cluster and in multi-node installation is generally provided by NFS.

Other Important Paths in dotCMS docker image.

Below are a list of other important paths in the dotCMS docker image.

Path DescriptionExampleNotes
Disk cache/data/localgenerally not mounted
Tomcat root directory/srv/dotserver/tomcat-9.0.41 
dotCMS webapp directory/srv/dotserver/tomcat-9.0.41/webapps/ROOT 
Log files/srv/dotserver/tomcat-9.0.41/logs file/srv/dotserver/tomcat-9.0.41/webapps/ROOT/starter.zipTo mount a custom file to be loaded at initial startup. You can also specify a via URL. See below for more information. file/data/shared/assets/license.zipThe should be added to the shared folder before starting dotCMS for the first time. After the initial startup, the licenses will live in the dotCMS database and this file is no longer needed.

Using a Custom

On first time startup, dotCMS will bootstrap the installation using the file found here /srv/dotserver/tomcat-9.0.41/webapps/ROOT/ By default dotCMS uses our bare bones “empty starter”. You can override this by either mounting in a custom file to /srv/dotserver/tomcat-9.0.41/webapps/ROOT/ or by specifing a CUSTOM_STARTER_URL environmental variable. If this variable is set, dotCMS will download this starter file and use it to bootstrap the intital install.


On this page