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
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.
- Java/JVM Configuration
- Tomcat Configuration
- Database Configuration
- Database Connection Pool Configuration - Optional
- ElasticSearch Configuration
- dotCMS Configuration
- Debugging dotCMS
- Mounting the Shared Folder
- Other Important Paths in dotCMS Docker
- Using a Custom starter.zip
Note: The file config-defaults.sh is a reference of different configuration variables and their default values.
|JAVA_OPTS_BASE||see file||These are the base java options passed to the jvm when started. The default should suffice for most installations.|
|JAVA_OPTS_AGENT||see file||This is the java agent used attached to the JVM. The default should suffice for most installations.|
|JAVA_OPTS_MEMORY||Java heap size used for Tomcat JVM. The default is intended for demonstration purposes only. For production environments, use |
|CMS_JAVA_OPTS||Arguements added here are added last in the jvm arguments and will override anything set before it.|
|CMS_CONNECTOR_THREADS||Maximum number of connector threads to be shared across all Tomcat connectors.|
|CMS_COMPRESSION||on||Enables/Disables GZIP compression in tomcat|
|CMS_COMPRESSIBLEMIMETYPE||see file||Enables/Disables GZIP compression for specific content types. The default should suffice for most installations.|
|CMS_ACCESSLOG_PATTERN||see file||The access log pattern used by tomcat. The default should suffice for most installations.|
|CMS_REMOTEIP_REMOTEIPHEADER||The header tomcat should use when resolving a remote server ip address.|
|CMS_REMOTEIP_INTERNALPROXIES||see file||The list of trusted proxies. If the remote ip address does not match these, the |
The following options allow you to specify how dotCMS should connect to the database and should be set for every dotCMS installation.
|DB_BASE_URL||JDBC-compliant URL to connect to the database.|
|DB_USERNAME||Username used to connect to the database server.|
|DB_PASSWORD||Password used to connect to 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.
|DB_DRIVER||The type of database used.|
Possible values are:
|DB_MAX_WAIT||Maximum lifetime (ms) of a connection in the pool.|
|DB_MAX_TOTAL||Maximum number of database connections permitted to the DB server.|
|DB_MIN_IDLE||Maximum amount of time (in seconds) that a connection is allowed to sit idle in the pool.|
|DB_VALIDATION_QUERY||SQL query to be executed to test the validity of connections.|
|DB_LEAK_DETECTION_THRESHOLD||Amount 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||Default transaction isolation level.|
|DOT_ES_ENDPOINTS||A 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_BASIC_USER||The username to use for BASIC auth of your elasticsearch servers|
|DOT_ES_AUTH_BASIC_PASSWORD||The password to use for BASIC auth of your elasticsearch servers|
|DOT_ES_AUTH_JWT_TOKEN||Token to use for JWT auth of your elasticsearch servers|
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
- Start with the configuration property name that you want to override.
- 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 "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": ' -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.:
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.
|Shared folder (includes /assets /felix)||this 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.
|Disk cache||generally not mounted|
|Tomcat root directory|
|dotCMS webapp directory|
|To mount a custom starter.zip file to be loaded at initial startup. You can also specify a starter.zip via URL. See below for more information.|
|The license.zip 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 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.