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

These examples 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 to Use Linux Images

The dotCMS Docker images are Linux based. If your Docker host machine is some Linux variant or OSX you do not need to change anything. However if you are using Docker for Windows you must configure it to run using Linux containers.

4. Set up Host to Run Elasticsearch Containers

For anything other than casual use or testing, it is recommended that you run dotCMS application containers with an external Elasticsearch container. To prepare your environment for hosting external ElasticSearch containers, please follow these directions for setting up your Docker Host machine: https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode

Example 1: Simple dotCMS Instance Running in Docker

docker run -itp 8080:8080 dotcms/dotcms:latest

Note - if you are running against the 'latest' tag, you might need to pull the latest version of the image, e.g.

docker pull dotcms/dotcms:latest

The example docker run command pulls down the latest released dotCMS Docker image from the public dotCMS Docker repository and automatically starts dotCMS in the container. The functionality of this dotCMS instance is essentially the same as if you were to download dotCMS to your local drive, uncompress the dotCMS release tar or zip file, and run the dotCMS startup script; however when you use Docker you are running a preinstalled dotCMS with all of its needed dependencies.

You should now be able to access your local dotCMS instance with this URL: http://localhost:8080/

Persisting the Data

In this example, the data is not persisted after the Docker container is shutdown. This is expected, since application containers are intentionally isolated from the file system and Docker will not persist data outside of the container unless explicitly instructed to do so.

If you wish to persist data outside the Docker container, you can do this in one of two ways:

  • Add the Docker -v option to map the data folders to Docker volumes.
  • Use the docker-compose command to both map Docker volumes and start Docker containers.
    • Please see below for a full docker-compose example.

Example 2: Multiple Containers With Persistent Data

This example demonstrates how to easily both set up Docker volumes and start other containerized services that work with dotCMS using the docker-compose application.

1. Create a 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, or create a local file named docker-compose.yml and copy the following text into the file:

version: '3.5'

networks:
  db_net:

volumes:
  cms-shared:
  cms-local:
  dbdata:

services:

  dotcms:
    image: dotcms/dotcms:latest
    ports:
      - "8080:8080"
    environment:
      "CMS_HEAP_SIZE": '1g'
      "CMS_JAVA_OPTS": '-XX:+PrintFlagsFinal'
      "PROVIDER_DB_DNSNAME": 'db'
    depends_on:
      - db
    volumes:
      - cms-shared:/data/shared
      - cms-local:/data/local
      #- [serverpath]/license.dat:/data/local/dotsecure/license/license.dat
      #- [serverpath]/license.zip:/data/shared/assets/license.zip
    networks:
      - db_net

  db:
    image: dotcms/postgres:latest
    volumes:
      - dbdata:/data/pg
    networks:
      - db_net
Optional: Loading license on startup

If you want dotCMS to startup as licensed, 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 (above).
  3. Uncomment and set the appropriate path to the license file.

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

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

4. Access dotCMS

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

Resources

This example sets up the following resources using Docker Compose:

Application Containers

This example starts separate Docker containers for each the following applications:

  • dotCMS
  • Postgres (database)
Docker Volumes

In this example, data is persisted in multiple named Docker volumes. The following data is stored in each of the volumes:

VolumeData Stored
cms-shareddotCMS assets
cms-localElasticSearch indexes and other local files
dbdataPostgres database files

What's Next?

Here we looked at a simple, two container example. If you are ready to see and experiment with more containers, you can checkout our other reference implementations. Each reference implemenation contains a readme file that explains how to run and clean up the example.