Docker / dotCMS on Amazon's Linux

Last Updated: Sep 22, 2020
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:
    • 2 Processors
    • 8GB 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
    • 8082
    • 8443

2. Update the AWS Instance

Perform an ssh to login to the AWS instance, and from the command line, run the commands:

## Update and enable Amazon Extras
sudo yum update -y
sudo  amazon-linux-extras install epel -y

## Install needed app/libs for docker/docker-compose
sudo yum install docker haveged gcc libffi-devel python3 python3-devel openssl-devel -y

## Start haveged (collects entropy for /dev/random)
sudo systemctl start haveged
sudo systemctl enable haveged

## 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

## Start/Enable Docker
sudo systemctl enable docker
sudo systemctl start docker

## Install pip / docker-compose
curl -o
python3 --user

~/.local/bin/pip install docker-compose

## set docker-compose permissions
sudo cp ~/.local/bin/docker-compose /usr/local/bin/docker-compose
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/dotcms
sudo chmod -R 777 /data

## Change to your work directory
cd /data/dotcms

## Chose how you want to start dotCMS  using 
## the example dotCMS docker-compose files

## Start with a demo site
curl -o docker-compose.yml

##   OR

## Start with an empty site
# curl -o docker-compose.yml

## Fire up dotCMS and tail the logs
docker-compose up -d && docker-compose logs -f

Once you have completed the steps above, you should see dotCMS start up normally. You can access dotCMS at your instance's IP address on port 8082, e.g.


(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).

(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 

(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.

Finish: Stop the Instance

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

docker-compose down

On this page


We Dig Feedback

Selected excerpt: