How to Run dotCMS in Push-Publish Mode with Docker-Compose

Push Publishing is a powerful feature of dotCMS that allows you to manage, synchronize, and deploy content seamlessly across multiple dotCMS environments. By designating one instance as a "sender" and one or more instances as "receivers", your editorial team can collaborate behind the scenes, test updates in a private authoring environment, and then push those updates to a live production environment when ready. In the dotCMS official documentation, you can see how quickly and reliably content moves between staging, production, or even multiple regional servers.

This approach brings several significant advantages. First, it supports a dedicated staging environment, where editors can thoroughly review new or updated content before pushing it live, ensuring higher quality and reducing the risk of exposing errors. Second, Push Publishing readily accommodates multisite or multichannel setups by letting you distribute content to different domains, languages, or regions from one central dotCMS instance. Third, by separating the authoring layer from the public-facing delivery environment, you can bolster security—editors work in a protected environment, while only approved content is exposed on the live server. Finally, for organizations that require scaling and high availability, Push Publishing offers an efficient way to distribute updates to a cluster of dotCMS nodes, guaranteeing consistent branding and messaging across various locations.

In this guide, you will learn how to configure a two-instance dotCMS cluster using Docker Compose so that one instance can "push" published content to another. We will walk through cloning the repository, spinning up both containers, and configuring the Push Publishing settings in the dotCMS user interface (UI). The process is illustrated with screenshots to make it easy to follow.

Prerequisites

Before you start, ensure you have the following:

• Docker and Docker Compose installed

• A basic understanding of Docker containers and networking

• Access to the dotCMS Push-Publish Docker Compose example

1. Cloning the Repository

First, clone the official dotCMS GitHub repository that includes the Docker Compose examples:

git clone https://github.com/dotCMS/core.git

Then navigate to the push-publish directory:

cd core/docker/docker-compose-examples/push-publish

Inside this folder, you'll find a docker-compose.yml file and a README.md explaining the container setup.

2. Overview of the Docker-Compose Setup

The docker-compose.yml in this folder defines two primary services:

1. dotcms-sender

   • The authoring or staging environment, from which content will be pushed.

2. dotcms-receiver

   • The destination environment that receives content from the sender.

By default, each container is mapped to local hostnames and ports that we'll use in the steps below.

3. Starting the Containers

Bring up the dotCMS instances with Docker Compose:

docker-compose up -d

You can monitor the logs:

docker-compose logs -f

After startup, you should have:

• dotcms-sender at http://localhost:8081

• dotcms-receiver at http://localhost:8082

Tip: If you want to use more user-friendly URLs, you can add hostnames to your hosts file /etc/hosts (Linux) or C:\Windows\System32\drivers\etc\hosts (Windows) file, although this is not a required step

127.0.0.1 dotcms-sender.local

127.0.0.1 dotcms-receiver.local

4. Logging into dotCMS

Both instances come with a default admin user:

• dotcms-sender: http://localhost:8081/dotAdmin

• dotcms-receiver: http://localhostl:8082/dotAdmin

Use the default admin credentials, for instance username admin@dotcms.com and password admin (or whatever is set in your environment).

5. Configuring Push-Publish Mode

Accessing the Publishing Environment Settings

1. In the System panel on the left-hand side, choose Configuration.

2. Then click the Publishing Environments tab across the top.

You should see a screen similar to the one below.

At this point, we're ready to create our first Push-Publish Environment on the sender.

Creating a New Publishing Environment

1. Click Add Environment (in the top-right corner).

2. Provide an Environment Name, for example receiver or authoring.

3. Under Push Mode, choose "Push to One Endpoint" if you'll be pushing to a single receiver.

4. Click Save.

Adding an Endpoint (The Receiver)

After creating the environment, add the remote endpoint that points to dotcms-receiver:

1. Click Add Endpoint next to your new environment.

2. Set the Endpoint Name (e.g. english-prod) and set Type to Dynamic dotCMS HTTP.

3. Check the box to Enable the endpoint.

4. Address To should be dotcms-receiver.local.

5. Port should be 8082.

Click Get Token in the Authorization Token field to generate a JSON Web Token (JWT).

Generating an Authorization Token

1. A popup will appear that requests credentials.

2. Enter a username and password for an admin account on the receiver.

3. Set the Expires Date for the token (e.g. a future date).

4. Optionally specify Allow Network (CIDR) to limit IP access.

5. Click Apply to generate the token.

Finally, click Save to store the endpoint.

Your "Authorization Token" field should now contain a long JWT token.

6. Push Publishing from the Content UI

Once your environment and endpoint are set up, you can push content from the standard dotCMS authoring interfaces.

Push Publishing an Asset

Go to Content → Digital Assets → Files. You’ll see a list of uploaded file assets.

1. Next to the file you want to publish, open the context menu (the three dots).

2. Select Push Publish.

A modal dialog will appear, allowing you to perform the push.

• I want to: Choose Push

• Filter: Select Everything and Dependencies (or your preferred option)

• Publish Date: The date on which the content will be published. Defaults to the current time. 

• Push To: Choose the environment you created, e.g. receiver

Then click Push.

7. Verifying the Content on the Receiver

After a successful push, the asset should appear on the dotcms-receiver instance. You can compare the Files listing on both sender and receiver to confirm.

In this side-by-side view, you can see that abstract-colorful-splash.jpg and company_logo.png exist and are published on both servers.

8. Helpful Tips & Troubleshooting

• Initialization Time: dotCMS can take a few minutes to fully initialize on startup. If you see errors with token generation or connectivity, wait a bit and try again.

• Token Expiration: Be mindful of your token's expiration date. If it expires, you'll need to regenerate a fresh JWT.

• Local DNS: If your dotcms-sender.local or dotcms-receiver.local hostnames fail to resolve, edit your hosts file as described above.

• Logs: If push publishing fails, check both containers' logs (docker-compose logs -f) to see detailed error messages.

Conclusion

Using Docker Compose to spin up a sender and receiver instance of dotCMS is a straightforward way to facilitate Push Publishing while in a local environment. Crucially, separating your authoring environment from your delivery environment provides multiple advantages:

• Streamlined Content Workflow: Editors can collaborate on content behind the scenes, review and schedule changes, and then push them to production at the right time.

• Enhanced Security: Restrict authoring to a protected environment while only exposing the delivery instance to the public.

• Clear Separation of Concerns: Focus staging on content creation and approvals, and let the live environment remain optimized for end-user traffic.

These benefits become even more significant at scale—especially when managing multiple sites, languages, or large editorial teams. For additional details, check the official dotCMS Push-Publish repository and the dotCMS official documentation for more advanced configurations and best practices.

Happy push-publishing!