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.
- Demo with a dotCMS Enterprise License
- Full Container Stack on Single Node
- Cluster with Full Container Stack on Single Node
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:
- Place the docker-compose.yml file in the current working directly.
- 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:
- Type
<Ctrl-C>
into the console. - 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:
- Start up the full dotCMS stack (see the Full Stack example, above).
- Install Enterprise licenses for all cluster nodes to be added.
- 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
- From the same directory that you ran docker-compose, run
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.