Getting Started with dotCMS in Docker Containers documentation for the dotCMS Content Management System

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 and Docker-Compose already installed. If you don't already have Docker and Docker-Compose installed, please install both applications using the instructions in the Docker install documentation for your platform.

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

The dotCMS Docker images are Linux based. This means that if your Docker host machine is some Linux variant or OSX 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

With dotCMS 5.3.0 and later versions, 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 5.3.0 and later on Docker for Windows, you must increase the value of the `vm.max_map_count1 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 application. 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:

Operating SystemCommandNotes
Linux
OSX
wget -O docker-compose.yml https://dotcms.com/run/demo && docker-compose up 
Windowscurl –output docker-compose.yml https://dotcms.com/run/demo
docker-compose up
  • Windows 10 v1803 and later ship with curl.
    • On earlier versions of windows, you will need to download curl for Windows before running this command.

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:8080/.

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:

VolumeData Stored
cms-shareddotCMS assets
dbdataPostgres database files
esdataElasticsearch data

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.