Docker Image Configuration Options documentation for the dotCMS Content Management System

dotCMS provides the following Docker images which you can use to run dotCMS and the necessary supporting applications in Docker containers.

Docker ImageDescriptionNotes
dotCMSThe content management system itselfCan be run by itself for demo purposes but for production use, should always be used with an external database.
PostgreSQLOpen source database engineAlthough most production environments will have their own database servers available, this container enables delivery of the full dotCMS stack in Docker containers, for demonstration, testing, and debugging purposes.
ElasticSearchContent search and indexing servicesHaving ElasticSearch in its own container allows it to be scaled independently of the other parts of the system, and offloads the CPU and memory needed to run it from the main dotCMS container.
HAProxyLoad balancer and proxy serverThis is not needed for environments which already have a load balancer, but is provided as part of the dotCMS Docker reference implementation because:
  • It enables delivery of containers for the entire stack that can be run with minimal environmental dependencies, which is important to quickly reproduce environments for testing and debugging multiple instances configured in a cluster.
  • It provides a reference of what configuration settings are needed to match the load balancer settings used in our internal testing.
HazelcastDistributed cache providerHaving a separate caching container allows caching to be scaled independently of the other layers.
Hazelcast Management Center (Optional)A management center for the Hazelcast cacheProvides insight into the internal details of the caches and the nodes hosting those caches. Completely optional; the full stack of other containers will run without this container.

Image Options

Each of the dotCMS Docker images has a number of options that you can set which control how the container is configured and run. You may use these options to change how the containers run without the need to modify the image.

For more information about any of these images, and the options you may set on them, please click on the name of the image in the table above.

dotCMS Docker Image

This image contains the core functionality of dotCMS and is capable of running with internal or external caching, ElasticSearch, and database depending on configuration.

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

Tomcat Options

OptionDescriptionDefault ValueNotes
CMS_HEAP_SIZEJava heap size used for Tomcat JVM1GThe 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_OPTSJava options passed to Tomcat JVMemptyThese 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_THREADSMaximum number of connector threads to be shared across all Tomcat connectors100This 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.
CMS_SMTP_HOSTHostname for the SMTP serversmtpThis server is used to send emails from workflows and other system communications.
CMS_RUNAS_UIDUser ID used to run the Tomcat process0 (runs as root user)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).
CMS_RUNAS_GIDUser Group used to run the Tomcat process0 (runs as root)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_SHAREDFlag to overwrite shared plugins with dotCMS pluginsfalseIf 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_OWNERFlag to change the owner of OSGI plugins to match the user running dotCMStrueIf 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.

Note: Several of these options are empty by default. This means that you must set the values for

OptionDescriptionDefault ValueNotes
PROVIDER_DB_DNSNAMEIP or hostname of database serveremptyFor 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_DRIVERThe type of database usedPOSTGRESPossible values are:
  • H2 (for demonstration purposes only)
  • POSTGRES (for PostgreSQL)
  • MYSQL
  • ORACLE
  • MSSQL (for Microsoft SQLServer)
PROVIDER_DB_URLJDBC-compliant URL to connect to the DBemptyThis setting is only needed to set custom options.
PROVIDER_DB_PORTDatabase TCP port numberemptyIf not set, will use the default port appropriate for the database (e.g. per PROVIDER_DB_DRIVER).
PROVIDER_DB_USERNAMEUsername used to connect to the DB serverdotcmsdbuserMust match the name of a valid database user on the database server.
PROVIDER_DB_PASSWORDPassword used to connect to the DB serverpasswordMust match the password for the specified PROVIDER_DB_USERNAME on the database server.
PROVIDER_DB_MAXCONNSMaximum number of database connections permitted to the DB server120Should be at least 20 higher than CMS_CONNECTOR_THREADS.

ElasticSearch Options

  • PROVIDER_ELASTICSEARCH_DNSNAMES
    • Description: IP address or hostname of external Elasticsearch service. If left unset, dotCMS will use internal Elasticsearch functionality. Keep in mind that if this value is set, you must have a valid license for dotCMS to use an external Elasticsearch service. If running a dotCMS cluster, this MUST be set the same on all clustered dotCMS nodes.
    • Default: empty - default is to use internal Elasticsearch service.
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_MIN
    • Description: The minimum amount of time (in seconds) to wait before attempting to discover Hazelcast service nodes. This is to permit the Hazelcast nodes to startup and be available for discovery.
    • Default: SERVICE_DELAY_DEFAULT_MIN - this is set in Dockerfile to be 1
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_STEP
    • Description: The amount of time (in seconds) to wait between discovery attempts.
    • Default: SERVICE_DELAY_DEFAULT_STEP - this is set in Dockerfile to be 3
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_MAX
    • Description: The maximum amount of time (in seconds) to wait before finishing service discovery.
    • Default: SERVICE_DELAY_DEFAULT_MAX - this is set in Dockerfile to be 30.
  • PROVIDER_ELASTICSEARCH_SVC_REFRESH
    • Description: How long (in seconds) for background Elasticsearch process to refresh service discovery.
    • Default: 10
  • PROVIDER_ELASTICSEARCH_CLUSTER_NAME
    • Description: Elasticsearch cluster name. For clustered dotCMS, all clustered nodes must have the same Elasticsearch cluster name.
    • Default: dotCMSContentIndex
  • PROVIDER_ELASTICSEARCH_PORT_TRANSPORT
    • Description: TCP port used for Elasticsearch transport protocol.
    • Default: 9300
  • PROVIDER_ELASTICSEARCH_ENABLE_HTTP
    • Description: Setting to enable Elasticsearch HTTP REST API. To enable Elasicsearch HTTP REST API, set to true and make sure to set PROVIDER_ELASTICSEARCH_ADDR_HTTP and PROVIDER_ELASTICSEARCH_PORT_HTTP as appropriate.
    • Default: false
  • PROVIDER_ELASTICSEARCH_ADDR_HTTP
    • Description: IP address for Elasticsearch HTTP REST API to bind to. To make this accessible outside of it container, you either need to assign a specific IP to the container and use that IP address or set this to 0.0.0.0 which will bind it to all IP addresses of the container.
    • Default: 127.0.0.1 - default binds to localhost and is not available outside of the container (even if PROVIDER_ELASTICSEARCH_ENABLE_HTTP is set to true).
  • PROVIDER_ELASTICSEARCH_PORT_HTTP
    • Description: TCP port used for Elasticsearch HTTP REST API.
    • Default: 9200

Hazelcast Options

  • PROVIDER_HAZELCAST_DNSNAMES
    • Description: IP address or hostname of external Hazelcast service. Leave 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.
    • Default: empty - default is to use embedded Hazelcast functionality.
  • PROVIDER_HAZELCAST_SVC_DELAY_MIN
    • Description: The minimum amount of time (in seconds) to wait before attempting to discover Hazelcast service nodes. This is to permit the Hazelcast nodes to startup and be available for discovery.
    • Default: SERVICE_DELAY_DEFAULT_MIN - this is set in Dockerfile to be 1
  • PROVIDER_HAZELCAST_SVC_DELAY_STEP
    • Description: The amount of time (in seconds) to wait between discovery attempts.
    • Default: SERVICE_DELAY_DEFAULT_STEP - this is set in Dockerfile to be 3
  • PROVIDER_HAZELCAST_SVC_DELAY_MAX
    • Description: The maximum amount of time (in seconds) to wait before finishing service discovery.
    • Default: SERVICE_DELAY_DEFAULT_MAX - this is set in Dockerfile to be 30
  • PROVIDER_HAZELCAST_GROUPNAME
    • Description: Hazelcast group name. For a shared cache to work properly, every clusterd dotCMS instance must use the same groupname.
    • Default: dotCMS
  • PROVIDER_HAZELCAST_PORT
    • Description: TCP port to use to communicate with Hazelcast service.
    • Default: 5701

PostgreSQL Docker Container

It is totally possible to use the database server of your choice or a different containerized database, but we provide this PostgreSQL container for demonstration and testing purposes.

The following configuration options are available for this image:

  • POSTGRES_CMS_USER
    • Description: Username that dotCMS will use to connect to database. This user is created with proper database permissions.
    • Default: dotcmsdbuser
  • POSTGRES_CMS_PASSWORD
    • Description: Password that dotCMS will use to connect to database. This password is set for the user created in the database.
    • Default: password
  • POSTGRES_CMS_DBNAME
    • Description: Name of the database that is created to store dotCMS data.
    • Default: dotcms
  • POSTGRES_ADMIN_PASSWORD
    • Description: Password for postgres admin user.
    • Default: empty

ElasticSearch Docker Container

  • PROVIDER_ELASTICSEARCH_HEAP_SIZE
    • Description: Java heap size used for ElasticSearch JVM. Value needed here depends heavily on number of contentlets and the amout of data being indexed.
    • Default: 1024m
  • PROVIDER_ELASTICSEARCH_DNSNAMES
    • Description: IP address or hostname of other external Elasticsearch services. If left unset, dotCMS will not attempt to discover other Elasticsearch services. If running a dotCMS cluster, this MUST be set the same on all clustered dotCMS nodes.
    • Default: empty - default is to not attempt to discover other Elasticsearch services.
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_MIN
    • Description: The minimum amount of time (in seconds) to wait before attempting to discover Elasticsearch service nodes. This is to permit the Elasticsearch nodes to startup and be available for discovery.
    • Default: SERVICE_DELAY_DEFAULT_MIN - this is set in Dockerfile to be 1
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_STEP
    • Description: The amount of time (in seconds) to wait between discovery attempts.
    • Default: SERVICE_DELAY_DEFAULT_STEP - this is set in Dockerfile to be 3
  • PROVIDER_ELASTICSEARCH_SVC_DELAY_MAX
    • Description: The maximum amount of time (in seconds) to wait before finishing service discovery.
    • Default: SERVICE_DELAY_DEFAULT_MAX - this is set in Dockerfile to be 30.
  • PROVIDER_ELASTICSEARCH_SVC_REFRESH
    • Description: How long (in seconds) for background Elasticsearch process to refresh service discovery.
    • Default: 10
  • PROVIDER_ELASTICSEARCH_CLUSTER_NAME
    • Description: Elasticsearch cluster name. For clustered dotCMS, all clustered nodes must have the same Elasticsearch cluster name.
    • Default: dotCMSContentIndex
  • PROVIDER_ELASTICSEARCH_PORT_TRANSPORT
    • Description: TCP port used for Elasticsearch transport protocol.
    • Default: 9300
  • PROVIDER_ELASTICSEARCH_ENABLE_HTTP
    • Description: Setting to enable Elasticsearch HTTP REST API. To enable Elasicsearch HTTP REST API, set to true and make sure to set PROVIDER_ELASTICSEARCH_ADDR_HTTP and PROVIDER_ELASTICSEARCH_PORT_HTTP as appropriate.
    • Default: true
  • PROVIDER_ELASTICSEARCH_ADDR_HTTP
    • Description: IP address for Elasticsearch HTTP REST API to bind to. To make this accessible outside of it container, you either need to assign a specific IP to the container and use that IP address or set this to 0.0.0.0 which will bind it to all IP addresses of the container.
    • Default: 127.0.0.1 - default binds to localhost and is not available outside of the container (even if PROVIDER_ELASTICSEARCH_ENABLE_HTTP is set to true).
  • PROVIDER_ELASTICSEARCH_PORT_HTTP
    • Description: TCP port used for Elasticsearch HTTP REST API.
    • Default: 9200
  • PROVIDER_ELASTICSEARCH_NODE_MASTER
    • Description: Setting that determines whether this node is eligible to be elected as the master Elasticsearch node.
    • Default: true
  • PROVIDER_ELASTICSEARCH_NODE_DATA
    • Description: Setting that determines whether this node is able to hold data and perform data related operations.
    • Default: true

HAProxy Docker Container

This image is built on top of the image provided by HAProxy. You can consult their configuration documentation here For the common and dotCMS specific configuration options, refer to the settings below:

  • CMS_DNSNAMES
    • Description: IP address or hostname of dotCMS service. Can be a multi-valued DNS record for round robin load balancing.
    • Default: dotcms
  • CMS_PORT_HTTP
    • Description: dotCMS port to direct HTTP traffic.
    • Default: 8081
  • CMS_PORT_HTTPS
    • Description: dotCMS port ot direct HTTPS traffic.
    • Default: 8082
  • HAPROXY_CERT_PATH
    • Description: Path to HAProxy certificate(s). Cert file format must be the concatenated subject certificate + intermediates certificate(s) + private key.
    • Default: empty
  • HAPROXY_ADMIN_PASSWORD
    • Description: Password for 'admin' user to admininstration interface. An empty password disables this functionality.
    • Default: empty
  • HAPROXY_MAINTENANCE_PAGE
    • Description: Path to raw HTTP response for 503 Server Unavailable maintenance page. Empty setting disables functionality.
    • Default: empty
  • HAPROXY_REDIRECT_HTTPS_ALL
    • Description: Flag to redirect all HTTP requests to HTTPS. When set to true, forces all requests to be HTTPS. If set to true, make sure certificate(s) are properly configured.
    • Default: false
  • HAPROXY_SERVICE_DELAY_MIN
    • Description: The minimum amount of time (in seconds) to wait before attempting to discover dotCMS service nodes. This is to permit the dotCMS nodes to startup and be available for discovery.
    • Default: SERVICE_DELAY_DEFAULT_MIN - this is set in Dockerfile to be 1
  • HAPROXY_SERVICE_DELAY_STEP
    • Description: The amount of time (in seconds) to wait between discovery attempts.
    • Default: SERVICE_DELAY_DEFAULT_STEP - this is set in Dockerfile to be 3
  • HAPROXY_SERVICE_DELAY_MAX
    • Description: The maximum amount of time (in seconds) to wait before finishing service discovery.
    • Default: SERVICE_DELAY_DEFAULT_MAX - this is set in Dockerfile to be 30.
  • HAPROXY_SERVICE_REFRESH
    • Description: How often (in seconds) for background discovery process to run discovery.
    • Default: 10

Hazelcast Docker Container

  • PROVIDER_HAZELCAST_HEAP_MIN
    • Description: Minimum Java heap size used for Hazelcast JVM. Performance testing and tuning will be needed to determine the optimal value for this setting.
    • Default: 128m
  • PROVIDER_HAZELCAST_HEAP_MAX
    • Description: Maximum Java heap size used for Hazelcast JVM. Performance testing and tuning will be needed to determine the optimal value for this setting.
    • Default: 1024m
  • PROVIDER_HAZELCAST_DNSNAMES
    • Description: IP address or hostnames of other Hazelcast instances. For single hazelcast instances, this can be left empty. For multiple Hazelcast instances, this can be a multiple value DNS name or a comma seperated list of IP addresses and hostnames.
    • Default: empty
  • PROVIDER_HAZELCAST_SVC_DELAY_MIN
    • Description: The minimum amount of time (in seconds) to wait before attempting to discover Hazelcast service nodes. This is to permit the Hazelcast nodes to startup and be available for discovery.
    • Default: SERVICE_DELAY_DEFAULT_MIN - this is set in Dockerfile to be 1
  • PROVIDER_HAZELCAST_SVC_DELAY_STEP
    • Description: The amount of time (in seconds) to wait between discovery attempts.
    • Default: SERVICE_DELAY_DEFAULT_STEP - this is set in Dockerfile to be 3
  • PROVIDER_HAZELCAST_SVC_DELAY_MAX
    • Description: The maximum amount of time (in seconds) to wait before finishing service discovery.
    • Default: SERVICE_DELAY_DEFAULT_MAX - this is set in Dockerfile to be 30
  • PROVIDER_HAZELCAST_GROUPNAME
    • Description: Hazelcast groupname. All clustered Hazelcast instances will need to use the same groupname and all dotCMS instance must have a matching PROVIDER_HAZELCAST_GROUPNAME setting.
    • Default: dotCMS
  • PROVIDER_HAZELCAST_PORT
    • Description: Port for Hazelcast to bind to. All clients must be configured to use this same port number.
    • Default: 5701
  • PROVIDER_HAZELCAST_MANCENTER_URL
    • Description: URL of optional Hazelcast Management Center application. If empty, no Management Center is utilized.
    • Default: empty

Hazelcast Management Center Docker Container

This totally optional image is available for additional insight into cache communications. The free version works for one or two nodes. For support of three or more hazelcast nodes, you will need to contact Hazelcast to purchase a license: https://hazelcast.com/contact/

There are not really any dotCMS specific configuration options here. When you first access the UI, you will be prompted to create your username and password.