Getting Started with dotCMS in Docker Containers

Are you ready to kick the tires and see dotCMS running in application containers? If so, it can be as simple as running a single Docker command, or you can dive into an example that's closer to real-world production use of application containers with a full Docker Compose example which starts multiple services and persists the dotCMS data in Docker volumes.

Inital Setup

Before running these examples, you need to ensure that you have all the necessary software and configuration on your computer, as outlined below.

1. Install Docker and Docker Compose

This example assume that you already have Docker already installed. If you don't already have Docker installed, please install it using the instructions in the Docker install documentation for your platform.

Note that orchestration depends upon the docker compose command, which is available by default in Docker Desktop. However, on more minimal installations, Docker Compose may need to be installed separately.

2. Ensure you have enough system resources

Keep in mind that each container has at least one running process which means that you need to make sure that enough CPU and memory are available for your containers to work well. It is recommended that at least 4 CPU cores be made available to Docker for usage in the containers. Each of the reference examples indicate how much memory you will need to run them safely. If you want to run all of the Docker containers on a single node, you should have at least 6GB of memory available to Docker.

For production use, you should perform capacity planning as you would without the applications being containerized.

3. Configure Docker for Windows

There are 2 steps you need to take for the dotCMS Docker images to run properly on Docker for Windows:

• Configure Docker for Windows to Use Linux Images
• Increase the amount of memory available to the Docker for Windows virtual machine

Configure Docker for Windows to Use Linux Images

The dotCMS Docker images are Linux based. This means that if your Docker host machine is some Linux variant or macOS you do not need to change anything, but if you are using Docker for Windows you must configure it to run using Linux containers.

For information on how to configure Docker for Windows to use Linux containers, please see the Docker for Windows documentation.

Increase the size of virtual machine map count

Elasticsearch is run as a separate Docker service. However, by default, the amount of memory that Docker for Windows allocates to the virtual machine does not provide enough memory to run both the dotCMS and Elasticsearch containers.

Therefore, to run dotCMS on Docker for Windows, you must increase the value of the vm.max_map_count for Docker for Windows, as follows:

• Open a command prompt as an administrator.
  • Right-click the command prompt icon or menu item and select Run as administrator.
• Execute the following commands in the command prompt:

  docker-machine ssh
  sudo sysctl -w vm.max_map_count=262144
  exit
  

• Close the command prompt.
• Restart Docker for Windows.

Basic Example

This basic example demonstrates how to easily both set up Docker volumes, and start other containerized services that work with dotCMS using the docker compose command. For additional and more sophisticated examples, please see the Docker Compose Examples documentation.

Quick Startup Commands

If you already have both Docker and Docker-Compose installed, you may start up this example with only one or two commands, as follows:

For more detailed instructions on how to use this example, please follow the steps below.

1. Create a Local Docker Compose File

To use Docker Compose you will need a docker-compose.yml file. You may download a sample docker-compose.yml file to a local folder from the URL https://dotcms.com/run/demo.

2. Optional: Load license on startup

If you want dotCMS to start up with a license already applied, you must map a valid dotCMS license file into a volume available to the dotCMS service. To do this:

1. Contact dotCMS for a dotCMS license file (license.dat or license.zip).
2. Find the commented lines in the “volumes:” section of the docker-compose.yml file.
3. Uncomment those lines, and set the appropriate path to the license file.

3. Pull Docker Images Locally

From the directory where your docker-compose.yml file is located, run the following command:

docker compose pull

This will make sure you have the latest versions of the Docker images that are used by the compose file.

4. Run Docker Compose

From the directory where your docker-compose.yml file is located, run the following command:

docker-compose up

In your terminal, you will see dotCMS and the other Docker containers starting up. The first time you run docker-compose with this file it may take several minutes to start, while dotCMS creates the database schema and imports the contents of the starter site into the database and index.

5. Access dotCMS

Once the startup process is complete, you can access the front end of dotCMS at http://localhost:8082/.

6. Shutting down the Container

To shut down dotCMS (and all containers started with it), run the following command:

docker compose down

Resources Used in this Example

This example sets up the following resources using Docker Compose.

Application Containers

Separate Docker containers are started for each the following applications:

• dotCMS
• Elasticsearch
• Postgres (database)

Docker Volumes

Data is persisted in multiple named Docker volumes. The following data is stored in each of the volumes:

Accessing Log Files

Tailing the Logs

You can tail the logs of the dotCMS docker container in real time using the following command (replace the {container ID} with the docker identifier for the container you want to access the logs for):

sudo docker logs -f {container ID}

Log File Location

You can access the log files directly within the Docker image by shelling into the image and navigating to the folder where the logs are stored.

• In the Docker images supplied by dotCMS, the logs are written to the /srv/dotserver/tomcat-8.5.32/logs folder.
• The location where the logs are stored can be changed via the /data/logs mapping in the docker-compose file.

Additional Examples

This example is the simplest reference implementation provided by dotCMS.

For more reference implementations, please see the Docker reference implementations on Github. Each reference implemenation contains a readme file that explains how to run and clean up the example.