Docker / dotCMS on Amazon's Linux documentation for the dotCMS Content Management System

This example demonstrates how to set up a scaleable dotCMS docker reference implementation cluster on Amazon's Linux 2 using docker-compose. It is intended as an example and not a perscription for running dotCMS in docker in production environments.

This example:

  • Starts dotCMS as a single node, and then scale it up to multiple nodes.
  • Is specific for running docker in Amazon's Linux 2 AMI.
    • Other linux distros will have different steps in order to configure their docker environments.
  • Shows you how to (optionally) build dotCMS from the a development branch of dotCMS.
  • Uses this the docker-compose file found dotCMS Docker Github repo.

Please click the sections below for detailed instructions and docker commands.

1. Start an Amazon Linux 2 Instance

Start up a new instance, and wait until the instance is ready.

Virtual Hardware Requirements
  • Minimum Hardware:
    • 4 Processors
    • 16GB RAM
    • The t3a.xlarge configuration is the most economical, but may not have enough resources for a heavily-used or production server.
  • Make sure the following ports are open in your security group:
    • 22
    • 80/443

2. Update the AWS Instance

Perform an ssh to login to the AWS instance, and run the following shell script:

sudo yum update -y
sudo yum install docker git -y

## set elasticsearch virtual memory settings
##    - Elasticsearch will not start without this

sudo sysctl -w vm.max_map_count=262144
sudo sysctl -w fs.file-max=100000

## make sure the settings stick
sudo sh -c "echo 'vm.max_map_count=262144' >> /etc/sysctl.conf"
sudo sh -c "echo 'fs.file-max=100000' >> /etc/sysctl.conf"
sudo sysctl -p

## add the ec2-user to docker
sudo usermod -a -G docker ec2-user

## edit docker file limits
sudo sh -c "echo \"OPTIONS='--default-ulimit nofile=65536:65536'\" >> /etc/sysconfig/docker"

## create a docker group and join it
newgrp docker

3. Start Docker and Docker-Compose

sudo service docker start

## download and install docker-compose
sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

## set docker-compose permissions
sudo chmod +x /usr/local/bin/docker-compose

## symbolic link docker-compose to your path
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

## test that it works
docker-compose --version

## make data directory
sudo mkdir -p /data/git
sudo chmod -R 777 /data

4. Build your dotCMS Docker Image

4a. Clone the dotCMS Docker Repo

cd /data/git
git clone

4b. (Optional) Build from a dotCMS Github Branch

If you want to just run the latest released version, you do not need to perform this step.

However, if you want to build from a branch of the dotCMS Github repo (including the master branch), you can build a new dotCMS docker image using the shell script below.

## In order to build our custom docker image, you need to be in the directory with the dotCMS Dockerfile
cd docker/images/dotcms/

## Build from MASTER
docker build --pull --no-cache --build-arg BUILD_FROM=COMMIT --build-arg BUILD_ID=origin/master -t dotcms/dotcms:latest .

## OR build rom a branch 
docker build --pull --no-cache --build-arg BUILD_FROM=COMMIT --build-arg BUILD_ID=origin/issue-16470-force-key-gen -t dotcms/dotcms:latest .


  • The -t dotcms/dotcms:latest tags this build as the latest dotcms build on the server.
    • When you start docker-compose, it uses this tag when spinning up the dotCMS.
  • If you commit to your branch or want to update to the latest master, you can:
    1. Run the docker build again,
    2. Tag the new build as the latest, and
    3. Restart dotcms in docker-compose.

4c. (Optional) Pre-Install a dotCMS License

To pre-install a dotCMS license pack, edit your docker-compose.yml file to install the license pack file into the Docker image.

  • Find the section of the docker-compose.yml file for the dotcms: Docker container.
  • In the volumes: section, uncomment the appropriate line for either a license file or license pack.
  • Edit the path in the uncommented line to point to your license file or license pack.

You may instead manually install a license pack after the Docker image is running (please see below).

5. Start Docker

5a. Run Docker-Compose

The following shell script commands change into the directory with the docker-compose file, and start the new dotCMS installation:

## change into the folder of the docker instance
cd /data/git/docker/examples/03-single_node-haproxy

## start docker-compose
##    - This brings up the whole stack, including the load balacer, elasticsearch, database and dotcms
docker-compose up -d 

## tail all the logs into the console window
docker-compose logs -f

5b. (Optional) Check the Status of the Docker Container

All normal docker and docker-compose commands may be used, where:

  • The name or identifier of the container may be used with docker commands (e.g. 03-single_node-haproxy_db_1).
  • The name of the container in the stack matches the name of that container within the docker-compose file (e.g. dotcms, elasticsearch, db, etc.).

The following docker and docker-compose commands may be useful to manage and check the status of the docker containers:

OperationCommandExamples (if appropriate)
View a list of running docker containersdocker ps 
Connect to any of the containers in the stackdocker exec -it {{CONTAINER NAME OR ID}} bash
  • docker exec -it 03-single_node-haproxy_db_1 bash
  • docker exec -it 03-single_node-haproxy_dotcms_1 bash
Copy files between the docker images and the hostdocker cp {{FILE}} {{CONTAINER}}:{{FOLDER IN CONTAINER}}docker cp ./docker-compose.yml 03-single_node-haproxy_db_1:/tmp/
Shut down dotCMS but leave the database runningdocker-compose scale dotcms=0 

5c. (Optional) Manually Install a dotCMS License

If you have not pre-installed a license, you can now log into the dotCMS back-end and upload a license pack. For more information, please see the License Management documentation.

6. (Optional) Scale up Additional dotCMS Instances

At this point, you can run dotCMS from the single instance you've already started. In addition, you may scale up to multiple instances using the following commands:

  • Scale dotcms to multiple instances (this example scales to 3 instances)
    docker-compose scale dotcms=3
  • Follow the logs until all the servers are up
    docker-compose logs -f
  • Access dotCMS
    • You should be able to login, start a reindex, go to the network tab and see your cluster.

Finish: Stop the Instance

When you are finished working with your dotCMS docker instance, you can stop the environment by running:

docker-compose down