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 fro 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 https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py --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 https://dotcms.com/run/demo
## OR
## Start with an empty site
# curl -o docker-compose.yml https://dotcms.com/run/clean
## 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:
Operation | Command | Examples (if appropriate) |
---|---|---|
View a list of running docker containers | docker ps | |
Connect to any of the containers in the stack | docker exec -it {{CONTAINER NAME OR ID}} bash |
|
Copy files between the docker images and the host | docker 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 running | docker-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