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

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_THREADS100Maximum 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.
CMS_SMTP_HOSTsmtpHostname for the SMTP server.
  • This server is used to send emails from Workflows and other system communications.
CMS_RUNAS_UID0
(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).
CMS_RUNAS_GID0
(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).

Integrated Container Database Options

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

Note:

  • These options only apply if you run the database within the integrated dotCMS Docker container.
    • If you run the database in a separate container using the full dotCMS Docker stack, please see the PostgreSQL Docker Container section, below.
  • 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)
  • MYSQL
  • ORACLE
  • 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_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_MAXCONNS120Maximum number of database connections permitted to the DB server.

Integrated Container ElasticSearch Options

NOTE: These options only apply if you run Elasticsearch within the integrated dotCMS Docker container. If you run Elasticsearch in a separate container using the full dotCMS Docker stack, please see the Elasticsearch Docker Container section, below.

OptionDefault ValueDescription
PROVIDER_ELASTICSEARCH_DNSNAMESempty
(use internal ES)
IP address or hostname of external Elasticsearch service.
  • If empty, dotCMS will use internal Elasticsearch functionality.
Important: 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.
PROVIDER_ELASTICSEARCH_SVC_DELAY_MINSERVICE_DELAY_DEFAULT_MIN
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 Elasticsearch attempts to access them.
PROVIDER_ELASTICSEARCH_SVC_DELAY_STEPSERVICE_DELAY_DEFAULT_STEP
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
PROVIDER_ELASTICSEARCH_SVC_DELAY_MAXSERVICE_DELAY_DEFAULT_MAX
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
PROVIDER_ELASTICSEARCH_SVC_REFRESH10Frequency (in seconds) for background Elasticsearch process to refresh service discovery.
PROVIDER_ELASTICSEARCH_CLUSTER_NAMEdotCMSContentIndexElasticsearch cluster name.
  • When using dotCMS clusters, all clustered nodes must have the same Elasticsearch cluster name.
PROVIDER_ELASTICSEARCH_PORT_TRANSPORT9300TCP port used for Elasticsearch transport protocol.
PROVIDER_ELASTICSEARCH_ENABLE_HTTPfalseEnable Elasticsearch HTTP REST API.
  • NOTE: For security purposes, it is recommended that you disable Elasticsearch HTTP REST API.
If you do wish to enable Elasicsearch HTTP REST API, you must do both of the following:
  1. Set this option to true.
  2. Set both PROVIDER_ELASTICSEARCH_ADDR_HTTP and PROVIDER_ELASTICSEARCH_PORT_HTTP options to appropriate values.
PROVIDER_ELASTICSEARCH_ADDR_HTTP127.0.0.1IP address for Elasticsearch HTTP REST API to bind to.
  • To make this accessible outside of the container, you need to either:
    • Assign a specific IP to the container and use that IP address, or
    • Set this option to 0.0.0.0, which will bind it to all IP addresses of the container.
  • If this option is set to 127.0.0.1 (the default), Elasticsearch binds to localhost and is not available outside the container (even if PROVIDER_ELASTICSEARCH_ENABLE_HTTP is set to true).
PROVIDER_ELASTICSEARCH_PORT_HTTP9200TCP port used for the Elasticsearch HTTP REST API.

Integrated Container Hazelcast Options

NOTE: These options only apply if you run Hazelcast within the integrated dotCMS Docker container. If you run Hazelcast in a separate container using the full dotCMS Docker stack, please see the Hazelcast Docker Container section, below.

OptionDefault ValueDescription
PROVIDER_HAZELCAST_DNSNAMESempty
(use embedded
Hazelcast)
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.
PROVIDER_HAZELCAST_SVC_DELAY_MINSERVICE_DELAY_DEFAULT_MIN
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.
PROVIDER_HAZELCAST_SVC_DELAY_STEPSERVICE_DELAY_DEFAULT_STEP
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
PROVIDER_HAZELCAST_SVC_DELAY_MAXSERVICE_DELAY_DEFAULT_MAX
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
PROVIDER_HAZELCAST_GROUPNAMEdotCMSHazelcast group name.
  • 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

Where /assets get stored:

[localpath]/data/shared:/data/shared

Where ES data and disk cache get stored

[localpath]/data/local:/data/local

tomcat root directory

/srv/dotserver/tomcat-8.5.32

log files

[localpath]/data/logs:/srv/dotserver/tomcat-8.5.32/logs

mount a custom starter

[localpath]/data/starter.zip:/srv/dotserver/tomcat-8.5.32/webapps/ROOT/starter.zip

mount osgi plugins (these will be added to felix/load on container startup)

[localpath]/plugins/osgi:/plugins/osgi

mount static plugins (these will be merged on container startup)

[localpath]/plugins/static:/plugins/static

mount a single license

[localpath]/license.dat:/data/local/dotsecure/license/license.dat

mount a license pack

[localpath]/license.zip:/data/shared/assets/license.zip

PostgreSQL Docker Container

This PostgreSQL container is provided as part of the dotCMS Docker stack for demonstration and testing purposes. You may use the database server and container of your choice in place of this container; please see the Database Configuration documentation for more information on how to configure dotCMS to use a different database.

OptionDefault ValueDescription
POSTGRES_CMS_USERdotcmsdbuserUsername that dotCMS will use to connect to database.
  • This must be a valid database user account, with proper database permissions.
POSTGRES_CMS_PASSWORDpasswordPassword that dotCMS will use to connect to database.
`POSTGRES_CMS_DBNAMEdotcmsName of the database that is created to store dotCMS data.
POSTGRES_ADMIN_PASSWORDemptyPassword for the postgres admin user account.

ElasticSearch Docker Container

OptionDefault ValueDescription
PROVIDER_ELASTICSEARCH_HEAP_SIZE1024mJava heap size used for ElasticSearch JVM.
  • The optimum value depends heavily on number of contentlets and the amout of data being indexed.
PROVIDER_ELASTICSEARCH_DNSNAMESempty
(do not attempt
discovery)
IP address or hostname of other external Elasticsearch services.
  • If empty, 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.
PROVIDER_ELASTICSEARCH_SVC_DELAY_MINSERVICE_DELAY_DEFAULT_MIN
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 Elasticsearch attempts to access them.
PROVIDER_ELASTICSEARCH_SVC_DELAY_STEPSERVICE_DELAY_DEFAULT_STEP
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
PROVIDER_ELASTICSEARCH_SVC_DELAY_MAXSERVICE_DELAY_DEFAULT_MAX
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
PROVIDER_ELASTICSEARCH_SVC_REFRESH10Frequency (in seconds) for background Elasticsearch process to refresh service discovery.
PROVIDER_ELASTICSEARCH_CLUSTER_NAMEdotCMSContentIndexElasticsearch cluster name.
  • When using dotCMS clusters, all clustered nodes must have the same Elasticsearch cluster name.
PROVIDER_ELASTICSEARCH_PORT_TRANSPORT9300TCP port used for Elasticsearch transport protocol.
PROVIDER_ELASTICSEARCH_ENABLE_HTTPfalseEnable Elasticsearch HTTP REST API.
  • NOTE: For security purposes, it is recommended that you disable Elasticsearch HTTP REST API.
If you do wish to enable Elasicsearch HTTP REST API, you must do both of the following:
  1. Set this option to true.
  2. Set both PROVIDER_ELASTICSEARCH_ADDR_HTTP and PROVIDER_ELASTICSEARCH_PORT_HTTP options to appropriate values.
PROVIDER_ELASTICSEARCH_ADDR_HTTP127.0.0.1IP address for Elasticsearch HTTP REST API to bind to.
  • To make this accessible outside of the container, you need to either:
    • Assign a specific IP to the container and use that IP address, or
    • Set this option to 0.0.0.0, which will bind it to all IP addresses of the container.
  • If this option is set to 127.0.0.1 (the default), Elasticsearch binds to localhost and is not available outside the container (even if PROVIDER_ELASTICSEARCH_ENABLE_HTTP is set to true).
PROVIDER_ELASTICSEARCH_PORT_HTTP9200TCP port used for the Elasticsearch HTTP REST API.
PROVIDER_ELASTICSEARCH_NODE_MASTERtrueEligibility for election as the master Elasticsearch node.
  • If set to false, this node will never be elected as the master ES node.
PROVIDER_ELASTICSEARCH_NODE_DATAtrueCan this node hold data and perform data related operations.
  • If set to false, Elasticsearch data will not be stored on this node.

HAProxy Docker Container

This Docker image is built on top of the Docker image provided by HAProxy. Please see the HAProxy configuration documentation for more information. It is recommended that you review the following settings and make appropriate changes when using the HAProxy container provided with the dotCMS Docker image:

OptionDefault ValueDescription
CMS_DNSNAMESdotcmsIP address or hostname of dotCMS service.
  • Can be a multi-valued DNS record for round robin load balancing.
CMS_PORT_HTTP8081dotCMS port to direct HTTP traffic.
CMS_PORT_HTTPS8082dotCMS port ot direct HTTPS traffic.
HAPROXY_CERT_PATHemptyPath to HAProxy certificate(s).
  • Cert file format must be the concatenated subject certificate + intermediates certificate(s) + private key.
HAPROXY_ADMIN_PASSWORDemptyPassword for the 'admin' user of the HAProxy admininstration interface.
  • An empty password disables HAProxy admin functionality.
HAPROXY_MAINTENANCE_PAGEemptyPath to raw HTTP response for 503 Server Unavailable maintenance page.
  • An empty setting disables this functionality.
HAPROXY_REDIRECT_HTTPS_ALLfalseRedirect all HTTP requests to HTTPS.
  • If true, forces all requests to be HTTPS.
  • If set to true, make sure certificate(s) are properly configured.
HAPROXY_SERVICE_DELAY_MINSERVICE_DELAY_DEFAULT_MIN
Set in Dockerfile to 1
Minimum time (in seconds) to wait before attempting to discover dotCMS service nodes.
  • This delay permits the dotCMS nodes to startup and be available for discovery before HAProxy begins directing requests to them.
HAPROXY_SERVICE_DELAY_STEPSERVICE_DELAY_DEFAULT_STEP
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
HAPROXY_SERVICE_DELAY_MAXSERVICE_DELAY_DEFAULT_MAX
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
HAPROXY_SERVICE_REFRESH10Frequency (in seconds) the background process runs discovery.

Hazelcast Docker Container

OptionDefault ValueDescription
PROVIDER_HAZELCAST_HEAP_MIN128mMinimum Java heap size used for Hazelcast JVM.
  • Performance testing and tuning will be needed to determine the optimal value for this setting.
PROVIDER_HAZELCAST_HEAP_MAX1024mMaximum Java heap size used for Hazelcast JVM.
  • Performance testing and tuning will be needed to determine the optimal value for this setting.
PROVIDER_HAZELCAST_DNSNAMESemptyIP 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.
PROVIDER_HAZELCAST_SVC_DELAY_MINSERVICE_DELAY_DEFAULT_MIN
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 the container finshes starting.
PROVIDER_HAZELCAST_SVC_DELAY_STEPSERVICE_DELAY_DEFAULT_STEP
Set in Dockerfile to 3
Time (in seconds) to wait between discovery attempts.
PROVIDER_HAZELCAST_SVC_DELAY_MAXSERVICE_DELAY_DEFAULT_MAX
Set in Dockerfile to 30
Maximum time (in seconds) to wait before finishing service discovery.
PROVIDER_HAZELCAST_GROUPNAMEdotCMSHazelcast groupname.
  • All clustered Hazelcast instances must use the same Hazelcast groupname.
  • All dotCMS instances must have the same PROVIDER_HAZELCAST_GROUPNAME setting.
PROVIDER_HAZELCAST_PORT5701Port for Hazelcast to bind to.
  • All clients must be configured to use this port number.
PROVIDER_HAZELCAST_MANCENTER_URLemptyURL of optional Hazelcast Management Center application.
  • If

Hazelcast Management Center Docker Container

This image is completely optional, but can be used to gain additional insight into cache communications. The free version of the Hazelcast Management Center allows you to run one or two Hazelcast nodes. For support of three or more Hazelcast nodes, you must contact Hazelcast to purchase a license.

There are no dotCMS-specific configuration options in this container. When you first access the UI, you will be prompted to create your username and password.

Files and Folders

The Docker image will copy files from specific locations in the path where the Docker image is located, to specific locations within the Docker image itself. Many of these locations are, in turn, mapped by the image into specific locations in the standard dotCMS image where these files are expected to be found.

To copy files into the Docker image when it is executed, you must place the appropriate folders as specified in the second column in the table below.

Files Placed in This FolderAre Copied to This Folder in the Docker ImageWhich Corresponds to this Folder in the dotCMS Distribution
[localpath]/data/shared/data/shared