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.
- 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
- 2. Update the AWS Instance
- 3. Start Docker and Docker-Compose
- 4. Build your dotCMS Docker Image
- 5. Start Docker
- 6. (Optional) Scale up Additional dotCMS Instances
- Finish: Stop the Instance
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:
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 "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(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 https://github.com/dotCMS/docker.git
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 .
-t dotcms/dotcms:latesttags this build as the latest dotcms build on the server.
- When you start
docker-compose, it uses this tag when spinning up the dotCMS.
- When you start
- If you commit to your branch or want to update to the latest master, you can:
- Run the docker build again,
- Tag the new build as the latest, and
- Restart dotcms in
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
- 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.
- The name of the container in the stack matches the name of that container within the docker-compose file (e.g.
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|
|Connect to any of the containers in the stack|
|Copy files between the docker images and the host|
|Shut down dotCMS but leave the database running|
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: