Docker Image Configuration Options documentation for the dotCMS Content Management System

dotCMS provides the following Docker image which you can use to run dotCMS in docker or in the orchestrator of your choice.

dotCMS Docker Image

This image contains the core functionality of dotCMS and 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. Configurable options are listed below:

For a reference of configuration variables and their default values, please see the file on the dotCMS Docker Github repository.

Tomcat Options

OptionDefault ValueDescription
CMS_HEAP_SIZE1GJava heap size used for Tomcat JVM.
  • The value needed depends heavily on size and quantity of assets as well as cache settings.
  • The default value is only for demonstration purposes
    • Most production installations will need to run with this set to 4G or higher.
CMS_JAVA_OPTSemptyJava options passed to Tomcat JVM.
  • These options are appended to the end of the default options and will therefore take precedence over any values previously set in the startup scripts.
CMS_CONNECTOR_THREADS600Maximum number of connector threads to be shared across all Tomcat connectors.
  • This value is merged into server.xml file and controls the total number of concurrent connections to the Tomcat server.
  • To avoid possible deadlocks under heavy load, this setting should be at least 20 lower than the PROVIDER_DB_MAXCONNS setting.
(root user)
User ID used to run the Tomcat process.
  • Use to run Tomcat as a user other than root.
  • Make sure this user has proper permissions to any filesystem that is mounted into the image (i.e. assets, plugins, etc).
(root group)
User Group used to run the Tomcat process.
  • Use to run Tomcat as a user other than root.
  • Make sure this group has proper permissions to any filesystem that is mounted into the image (i.e. assets, plugins, etc).
CMS_PLUGINS_OSGI_OVERWRITE_SHAREDfalseOverwrite shared plugins with dotCMS plugins.
  • If set to true, will overwrite OSGI plugins with the OSGI plugins located at /plugins/osgi in the dotCMS image.
  • WARNING: If this option is set to true, you may overwrite plugins that were uploaded via the backend UI or that were manually copied into the felix load directory.
CMS_PLUGINS_OSGI_FIX_OWNERtrueChange the owner of OSGI plugins to match the user running dotCMS.
  • If set to true, the owner of OSGI plugins will be changed to match the values set via CMS_RUNAS_UID and CMS_RUNAS_GID (see above).

Database Options

The following options allow you to specify how dotCMS should connect to the database.


  • Several of these options are empty by default. This means that you must set these values for these options for the dotCMS Docker container to work.
OptionDefault ValueDescription
PROVIDER_DB_DNSNAMEemptyIP or hostname of database server.
  • For a database running in a container, this is the service name.
  • For an external database server (database not running in a container), this should either be the IP address or a DNS name that is resolvable and accessible from inside the dotCMS container.
PROVIDER_DB_DRIVERPOSTGRESThe type of database used.
Possible values are:
  • H2 (for demonstration purposes only)
  • POSTGRES (for PostgreSQL)
  • MSSQL (for Microsoft SQLServer)
PROVIDER_DB_URLemptyJDBC-compliant URL to connect to the database.
  • Only needed if you wish to set custom options.
PROVIDER_DB_PORTemptyDatabase TCP port number.
  • If not set, will use the default port appropriate for the database (e.g. per PROVIDER_DB_DRIVER).
PROVIDER_DB_DBNAMEemptyThe database name dotCMS should connect to. It must exist before initial startup.
PROVIDER_DB_USERNAMEdotcmsdbuserUsername used to connect to the database server.
  • Must match the name of a valid database user on the database server.
PROVIDER_DB_PASSWORDpasswordPassword used to connect to the database server.
  • Must match the password for the specified PROVIDER_DB_USERNAME on the database server.
PROVIDER_DB_MAXCONNS200Maximum number of database connections permitted to the DB server.

ElasticSearch Options

OptionDefault ValueDescription
PROVIDER_ELASTICSEARCH_ENDPOINTShttps://localhost:9200A comma separated list of elasticsearch endpoints/servers that dotCMS will connect to. dotCMS will load balance between the endpoints in this list.
PROVIDER_ELASTICSEARCH_AUTH_TYPEBASICEither BASIC or NONE. Setting this to BASIC means you need to provide a username and password. Setting this to NONE will prevent dotCMS from passing the Basic Auth header when connecting to your ES service.
PROVIDER_ELASTICSEARCH_AUTH_BASIC_USERadminThe username to use for BASIC auth of your elasticsearch servers
PROVIDER_ELASTICSEARCH_AUTH_BASIC_PASSWORDadminThe password to use for BASIC auth of your elasticsearch servers

dotCMS Options

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 match 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": '-Xdebug -Xrunjdwp: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.

Hazelcast Options {#dotCMSHazelcastOptions} (deprecated)

NOTE: These options only apply 1) if you are not running the default PostgresPubSub clustering and 2) if you run Hazelcast within dotCMS. If you need more Hazelcast configuration options, for example, to connect to a remote hazelcast cluster, we suggest mounting the hazelcast.xml directly into dotCMS.

OptionDefault ValueDescription
(use embedded
IP address or hostname of external Hazelcast service.
  • Leave empty (unset) for embedded Hazelcast functionality.
  • If running more than one dotCMS instance in a cluster, this must be set the same for all dotCMS instances so that the cache can be synchronized between the nodes.
Set in Dockerfile to 1
Minimum time (in seconds) to wait before attempting to discover Hazelcast service nodes.
  • This delay permits the Hazelcast nodes to startup and be available for discovery before they are accessed.
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
  • For a shared cache to work properly, every clustered dotCMS instance must use the same groupname.
PROVIDER_HAZELCAST_PORT5701TCP port to use to communicate with Hazelcast service.

Important docker volume / mapped paths

The dotCMS docker image provides provides a number of paths that can be mapped to either local or named volumes in order to provide external persistance and management. Below is a list of some of those paths

Path DescriptionExampleNotes
Assets folder (/assets)[localpath]/data/shared:/data/shared 
Disk cache[localpath]/data/local:/data/local 
Tomcat root directory/srv/dotserver/tomcat-9.0.41 
dotCMS webapp directory/srv/dotserver/tomcat-9.0.41/webapps/ROOT 
Log files[localpath]/data/logs:/srv/dotserver/tomcat-9.0.41/logs file[localpath]/data/ mount a custom file to be loaded at initial startup
OSGI plugins[localpath]/plugins/osgi:/plugins/osgiThese will be added to the felix/load folder on container startup
Static plugins (deprecated)[localpath]/plugins/static:/plugins/staticThese will be merged on container startup file[localpath]/ mount a license pack (you can also just add the into your mounted assets folder).