Docker Examples

This document gives several 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 primer for dotCMS developers, system administrators, and dev ops engineers.

See Docker's documentation for installation instructions, or to learn more about the Docker Compose tool we use in the examples below.

Why Docker Compose?

While the containers provided by dotCMS can be run in any Linux Docker-compatible orchestrator, we have chosen to provide our reference implementation using Docker Compose files, because:

• The YAML file for Docker Compose and swarm is easy to understand, and is an effective way of communicating the needed configuration for services, volumes, and networks.
• This format makes it easy for simple POCs and for developers to use the entire stack locally on their development machines.
• It is easy to take the information from these examples to deploy these services in the orchestrator of your choice.

Basic Up and Down

To get started with one of the examples below:

1. Download an example's docker-compose.yml to your working directory.
2. Run the command: docker compose up.

Once it's spun up the containers, you can access dotCMS on port 8082 of your Docker host (e.g. http://localhost/). If you're using the Docker Desktop application, its dashboard will also surface an “Open in Browser” button under its Containers menu:

To take down the cluster, use <Ctrl-C> to halt execution, then use the docker compose down command.

Note that Docker uses named volumes to persist data between runs; once a container is stopped, the data from the assets, databases, and ElasticSearch indexes will still persist until you explicitly remove the volumes, such as with the command docker system prune.

Examples

The following demo configurations are provided and maintained by dotCMS. The examples run a full “container stack” with separate containers for dotCMS, the database, and other services which represent a normal enterprise-type Docker deployment. All containers are run locally on a single machine. Each reference implementation comes with a readme file that provides instructions on how to properly start and clean up the examples.

To access the files, select a Demo Configuration from the table below.

Important Implementation Details

The Reference implementations make use of the following open-source technologies to implement and manage the images:

• The S6 Overlay system is used for configuration and initialization.
• Dockerize is used for templatization of configuration.

Demo with a dotCMS Enterprise License

Applying a license to enable Enterprise functionality involves the same dotCMS demo/starter as in the previous example, with a small change to the YAML file. You will need either a license.dat or license.zip file.

With a license.zip file:

You may notice that the single-node examples already have the following lines under the dotcms structure:

    volumes:
      - cms-shared:/data/shared
      #- {license_local_path}/license.zip:/data/shared/assets/license.zip

Simply remove the # to uncomment that line, and then replace {license_local_path} with the location of your license.zip file. An example result:

    volumes:
      - cms-shared:/data/shared
      - /Users/alice/docker_license/license.zip:/data/shared/assets/license.zip

Please note that the path to the license file must be a fully qualified path; no relative paths are permitted in this command.

With a license.dat file:

Similar to the above, ensure the dotcms structure's volumes point to the local file:

    volumes:
      - cms-shared:/data/shared
      - /Users/alice/docker_license/license.dat:/data/local/dotsecure/license/license.dat

Again, the local path must be a fully qualified path.

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. They can be applied in the same fashion as above, or by uploading the license.zip file in the dotCMS admin panel, via System > Configuration > Licensing.

To run a dotCMS cluster in Docker:

1. Start up dotCMS as described 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.