Docker Examples documentation for the dotCMS Content Management System

This document gives several specific examples of how dotCMS can be run with Docker. This is not intended to be a primer on Docker itself; there are many other sources of information on Docker available. This is essentially a “dotCMS in Docker” primer for dotCMS developers, system administrators, and devOps engineers.

• Simple Demo from the Command Line
• Demo with a dotCMS Enterprise License
  • With a license.dat file
  • With a license.zip file
  • License File Path
• Full Container Stack on Single Node
  • docker-compose.yml File
  • Starting Up
  • Shutting Down
  • Clearing Persisted Data
• Cluster with Full Container Stack on Single Node
  • Cluster Licenses
  • Starting Up
  • Scaling Up and Down

Simple Demo from the Command Line

The following simple example runs dotCMS in Docker from the Linux command line:

docker run -itp 8080:8080 dotcms/dotcms:latest

Note:

• This creates and runs the dotCMS Demo/Starter site when it launches.
  • This is very similar to extracting and running dotCMS from the release distribution; it's just doing it using Docker.
• It uses the default H2 database.
• This runs without an Enterprise license, so only Community Edition functionality is available.
• After dotCMS finishes initializing, you can access dotCMS on port 8080.
• When you are done, press <Ctrl-C> to stop the dotCMS container.

Warning: Since containers are isolated by default, the dotCMS data you create in this instance will not persist after you shut down dotCMS. Please see below for an example that persists the data across multiple runs.

Demo with a dotCMS Enterprise License

The following commands run the same dotCMS demo/starter site as in the previous example, but apply an Enterprise license (via either a license.dat or license.zip file) to the instance, to enable Enterprise functionality:

With a license.dat file:

docker run -itp 8080:8080 -v ${PWD}/license.dat:/data/local/dotsecure/license/license.dat  dotcms/dotcms:latest

With a license.zip file:

docker run -itp 8080:8080 -v ${PWD}/license.zip:/data/shared/assets/license.zip  dotcms/dotcms:latest

License File Path

Note:

• In the examples, ${PWD} just expands to the directory you are running the command from.
  • You can replace this with a different path if your license file is in a different location.
• The path to the license file must be a fully qualified path.
  • No relative paths are permitted in this command.

Full Container Stack on Single Node

This example runs a full “container stack” with separate containers for dotCMS, the database, and other services which represent a more normal enterprise-type Docker deployment. All containers are run locally on a single machine.

This example may be helpful for testing and debugging, and is likely the base example to use if you want to setup a standard demo but use a database other than the default H2 database.

docker-compose.yml File

This example uses a docker-compose.yml file which can be found on the dotCMS GitHub repository.

• The containers run and the order they are run is defined in the docker-compose.yml file.
  • This file can be modified as needed.
• The default implementation runs the following containers:
  • haproxy (load balancer)
  • External Hazelcast (caching)
  • Hazelcast Management Center (hazelcast-mancenter - monitors Hazelcast caching)
  • Two separate ElasticSearch containers (demonstrating a scalable Elasticsearch implementation)
  • PostgreSQL (database)
  • dotCMS

Starting Up

To start up the full dotCMS Docker stack:

1. Place the docker-compose.yml file in the current working directly.
2. Run the docker-compose up command.

Note:

• You can access dotCMS on port 80 of your Docker host (e.g. http://localhost/).
• This option uses Docker named volumes to persist data between runs.
  • Once the container is stopped the data from the assets, DB, and ES indexes will be persisted until you remove the docker volumes.

Shutting Down

To shutdown all the containers in the full dotCMS Docker stack:

1. Type <Ctrl-C> into the console.
2. Run docker-compose down in the console.

Clearing Persisted Data

If you want to delete the persisted data, then after the containers have been stopped, you must run the relevant Docker container and volume prune commands to remove the data from the named volumes. If you do not remove this data, it will be used next time you run docker-compose up with the same docker-compose.yml file or whenever those volume names are used by another deployment (config file or command line options).

Cluster with Full Container Stack on Single Node

To run a dotCMS cluster on a single node, you can use a full blown orchestrator like Swarm, Kubernetes, etc or you can use docker-compose. The following example uses docker-compose, and assumes that:

• You have **already run docker-compose up.
• dotCMS and the other related containers are already running on your system.

Once the full stack of containers is running, you can easily add additional instances of containers like dotCMS.

Cluster Licenses

For dotCMS clustering to work, you must have multiple Enterprise licenses installed.

• You must have at least as many licenses loaded in the system as the number of dotCMS containers you plan to run.
• You can install these licenses by either:
  • Uncommenting the the license.zip line in the docker-compose file to map a valid Enterprise license pack, or
  • Uploading the license.zip file in the dotCMS back-end UI (via System->Configuration->Licensing).

Starting Up

To run a dotCMS cluster in Docker:

1. Start up the full dotCMS stack (see the Full Stack example, above).
2. Install Enterprise licenses for all cluster nodes to be added.
3. Start one additional dotCMS container for each additional node in the cluster.
   • From the same directory that you ran docker-compose, run docker-compose up -d --scale dotcms=2

Scaling Up and Down

While it is technically possible to scale up or down multiple dotCMS nodes and Docker containers at a time, at this time we recommend that you only scale up or down one instance at a time.

• It is advisable to scale slowly, since it can take significant time to copy indexes and other files, and it is best to ensure the system is in a fully stable state before additional scaling.
• However, with appropriate hardware resources and configuration, it is possible to design a Docker implementation that scales up and down more quickly.
  • If you wish to do this please contact dotCMS support for assistance so we can help ensure your success.