Docker Configuration Options

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

environment:
    "JAVA_OPTS_MEMORY": '-Xmx4g'
    "DB_BASE_URL": "jdbc:postgresql://db.dotcms.site/dotcms"
    "DB_USERNAME": 'dotcmsdbuser'
    "DB_PASSWORD": 'password'
    "DOT_ES_ENDPOINTS": 'https://es.dotcms.site:9200'
    "DOT_ES_AUTH_BASIC_USER": 'esadmin'
    "DOT_ES_AUTH_BASIC_PASSWORD": 'espassword'
volumes:
    - /volumes/dotcms-share:/data/shared

Even TL;DRer: Generate A Docker Compose YAML

Our Current Releases page includes a simple tool to remove all guesswork: You can generate a YAML file for use with docker compose that'll have you up and running with a current version of dotCMS in mere seconds!

Docker Configuration

This dotCMS image is capable of being configured to run against a variety 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 config-defaults.sh is a reference of different configuration variables and their default values.

Java/JVM Configuration

Tomcat Configuration

Database Configuration

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

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.

ElasticSearch Configuration

dotCMS Configuration — DOT notation

dotCMS allows you to override any config option in the dotmarketing-config.properties file or the dotcms-cluster-config.properties 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.
  • Example: CACHE.DEFAULT.CHAIN
• Then replace any periods (dots) in the property name with underscores.
  • Example: CACHE_DEFAULT_CHAIN
• Finally add DOT_ to the beginning of the name.
  • Example: DOT_CACHE_DEFAULT_CHAIN

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 "DOT_CACHE_DEFAULT_CHAIN=com.dotmarketing.business.cache.provider.timedcache.TimedCacheProvider"

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": ' -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:8000'

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

    ports:
        - “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.

Other Important Paths in dotCMS docker image

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

Using a Custom starter.zip

On first time startup, dotCMS will bootstrap the installation using the starter.zip file found here /srv/dotserver/tomcat-9.0.41/webapps/ROOT/starter.zip. By default dotCMS uses our bare bones “empty starter”. You can override this starter.zip by either mounting in a custom starter.zip file to /srv/dotserver/tomcat-9.0.41/webapps/ROOT/starter.zip 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.

"CUSTOM_STARTER_URL": 'https://repo.dotcms.com/artifactory/libs-release-local/com/dotcms/starter/20230712/starter-20230712.zip'