Operating System CentOS

How to Install dotCMS on AlmaLinux 9 or Rocky Linux 9 with Docker

Run dotCMS, PostgreSQL and OpenSearch with Docker Compose on AlmaLinux 9 or Rocky Linux 9, harden the example file and log in to the back end.

This guide gets a single-node dotCMS instance running on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 with Docker Compose: the dotCMS application, a PostgreSQL database and an OpenSearch index, each in its own container with persistent volumes. At the end you can log in to the dotCMS back end at /dotAdmin and start building a site.

CentOS 7 reached end of life on 30 June 2024, and the method older tutorials describe (unpacking a Tomcat bundle under /opt/dotcms, installing Java 8 and pointing it at a local PostgreSQL) no longer matches how dotCMS is delivered. The current documentation and the project's own examples run dotCMS from the dotcms/dotcms container image, so that is the route used here.

Requirements

  • A 64-bit server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 and a user with sudo rights.
  • Memory and CPU: the dotCMS Docker documentation asks for at least 6 GB of memory available to Docker and recommends 4 CPU cores when all containers run on one host.
  • A domain name pointed at the server (the examples use cms.example.com) if you want to publish the site over HTTPS.

Step 1: Install Docker Engine and the Compose plugin

Docker's RPM repository for CentOS is the one used on the RHEL 9 rebuilds:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Check that the engine and the Compose plugin answer:

sudo docker version
sudo docker compose version

Step 2: Download the single-node Compose file

dotCMS keeps its Compose examples in the docker/docker-compose-examples directory of its source repository. The single-node example starts an empty instance; single-node-demo-site is the same stack with the demo starter site loaded.

sudo mkdir -p /opt/dotcms
cd /opt/dotcms
sudo curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/dotCMS/core/main/docker/docker-compose-examples/single-node/docker-compose.yml

The file defines three services:

ServiceImageData volume
dbpgvector/pgvector:pg18 (PostgreSQL 18)dbdata
opensearchopensearchproject/opensearch:1opensearch-data
dotcmsdotcms/dotcms:latestcms-shared (mounted at /data/shared)

Step 3: Adjust the file for a public server

The example is written for a workstation: every password is a placeholder and several internal ports are published. Docker publishes ports by its own firewall rules, so they are reachable from the internet even when firewalld does not list them. Edit the file before the first start:

sudo nano /opt/dotcms/docker-compose.yml
  • Admin password. Replace the value of DOT_INITIAL_ADMIN_PASSWORD (shipped as admin) with a long password of your own. It is applied when the instance is first created.
  • Database password. Change POSTGRES_PASSWORD in the db service and DB_PASSWORD in the dotcms service to the same new value.
  • OpenSearch ports. Delete the ports: block of the opensearch service (9200 and 9600). dotCMS reaches OpenSearch over the internal Compose network and does not need them.
  • dotCMS ports. In the dotcms service keep 8082 (HTTP) and 8443 (HTTPS) and remove 8000 (Java debugger) and 4000 (Glowroot monitoring UI). The file's own comment says the Glowroot web UI must not be exposed in production; set GLOWROOT_WEB_UI_ENABLED to 'false' as well.
  • Image tag. dotcms/dotcms:latest follows every new release. For a server you intend to keep, replace latest with a specific release tag from the dotCMS releases page so that an image pull never upgrades you by surprise.

After editing, the port list of the dotcms service looks like this:

    ports:
      - "8082:8082"
      - "8443:8443"

Let Compose validate the result. It prints the merged configuration, or an error with a line number if the indentation is wrong:

cd /opt/dotcms
sudo docker compose config

Step 4: Start dotCMS

cd /opt/dotcms
sudo docker compose up -d

The first start downloads the images, creates the database schema and builds the search indexes, which takes several minutes. Follow the application log until the server reports that it has started:

sudo docker compose logs -f dotcms

Press Ctrl+C to leave the log; the containers keep running. Check their state at any time with:

sudo docker compose ps

Step 5: Log in

Open https://203.0.113.10:8443/dotAdmin (replace the address with your server's). The container serves HTTPS on port 8443 with a self-signed certificate, so the browser shows a warning the first time; plain HTTP is available on port 8082.

Sign in as admin@dotcms.com with the password you set in DOT_INITIAL_ADMIN_PASSWORD. Then change the password and the e-mail address of that account in the user settings, because the login name is the same on every dotCMS installation.

Without a licence file dotCMS runs as the Community Edition. If you have a licence pack, the Compose file contains a commented volume line that mounts license.zip to /data/shared/assets/license.zip.

Step 6: Put a trusted certificate in front

For a real site, terminate TLS in a reverse proxy on the host (Nginx, Apache or Caddy) and forward requests to dotCMS on port 8082. Bind the container port to the loopback interface so that only the proxy can reach it, and drop the 8443 mapping:

    ports:
      - "127.0.0.1:8082:8082"

Apply the change with sudo docker compose up -d, then open the web ports for the proxy:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

On AlmaLinux and Rocky Linux, SELinux blocks a proxy from opening outbound connections until you allow it:

sudo setsebool -P httpd_can_network_connect 1

Maintenance

Backups

Your content lives in two places: the PostgreSQL database and the cms-shared volume (uploaded assets). The search index can be rebuilt from those. Dump the database with the tools inside the db container:

cd /opt/dotcms
sudo docker compose exec db pg_dump -U dotcmsdbuser dotcms | gzip > ~/dotcms-$(date +%F).sql.gz

Updates

Read the release notes, take a backup, change the image tag in docker-compose.yml if you pinned one, and recreate the containers:

cd /opt/dotcms
sudo docker compose pull
sudo docker compose up -d

Stopping and removing

sudo docker compose down stops and removes the containers and keeps the volumes. Adding -v deletes the volumes and all content with them.

Troubleshooting

  • A container keeps restarting or disappears. Run sudo docker compose logs opensearch and sudo docker compose logs dotcms. On a host with too little memory the kernel kills the Java processes; sudo dmesg | grep -i "out of memory" confirms it.
  • OpenSearch complains about vm.max_map_count. Raise the kernel limit and make it permanent:
    echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-opensearch.conf
    sudo sysctl --system
  • The new admin password is not accepted. DOT_INITIAL_ADMIN_PASSWORD only applies to an empty database. If the instance was already initialised with the placeholder, log in with that and change the password in the back end.

Frequently asked questions

Can I still install dotCMS without Docker?

The installation documentation and the maintained examples are built around the container image, and that is where configuration is documented (environment variables prefixed with DOT_). A hand-built Tomcat installation leaves you without a supported upgrade path, so use the image even on a single server.

How do I load the demo site instead of an empty instance?

Use the Compose file from the single-node-demo-site example directory in the same repository. It is the same stack with a starter site configured through CUSTOM_STARTER_URL. A starter is only imported into an empty database.

Why does dotCMS use OpenSearch 1.x when newer versions exist?

The Compose examples pin the opensearchproject/opensearch:1 image because that is the search version dotCMS is built and tested against. Do not change the major version on your own; follow the image named in the example for the dotCMS release you run.

Where do I change settings that used to live in properties files?

In the environment: section of the dotcms service. JVM memory is set with CMS_JAVA_OPTS (the example uses -Xmx1g), the time zone with TZ, and dotCMS properties with variables that start with DOT_. Recreate the container with sudo docker compose up -d after a change.

Share story:

Continue reading other guides on How VPS.