dotCMS logodotCMS logo

Managing Evergreen On Premise

Managing an on-premise dotCMS Evergreen installation is a relatively straightforward process, achievable through either automation or a manual devops maintenance cadence. Regularly updating your dotCMS installation allows you to experience a SaaS-like, modern environment with up to date security patches and fixes all while retaining full control over your dotCMS instances.

Surprisingly, frequent updates to your dotCMS environment become easier to manage than infrequent, large-scale upgrades. This is partly because dotCMS is designed for automatic self-updates, including data model updates, with a continuous focus on backward compatibility and minimizing breaking changes.

The best choice between using an automated or manual update process depends on several factors, including:

  • The number of plugins in use
  • The complexity of your implementation
  • The sophistication and rigor (maturity) of your development operations
  • The presence of automated tests for your site’s functionality

Ultimately, the best approach — automation or a more manual process — is determined by your specific use case.

Manually Updating Your dotCMS Installation#

  1. Find the latest dotCMS release by navigating to the dotCMS GitHub repo and checking out the latest released versions: https://github.com/dotCMS/core/releases. Copy the latest release number to your clipboard — e.g., 25.07.14-1. (Make sure to ignore any “Draft” releases.)

  2. Next, go to the dotCMS docker hub repo — https://hub.docker.com/r/dotcms/dotcms/tags — and search for the release number by the tag you copied:

    While both tags point to the same Docker image, it's best practice to use the one that includes the Git commit hash for clarity and traceability. For example, for version 25.07.14-1_4a82981, update your deployment to use:

image: dotcms/dotcms:25.07.14-1_4a82981

Update your configuration or manifests with the new tag, commit the changes, and redeploy using a rolling strategy.

As each new pod comes up, it will apply any required data definition language or startup tasks. These database changes are designed to remain backward-compatible with versions for at least one month. This means that dotCMS 25.07 can run side by side with a dotCMS 25.06 instance and allows for seamless upgrades.

After all instances are updated:

  • Confirm that customizations are still functioning
    • Ensure custom plugins are marked “Active” and behaving as expected

To verify your running version, check the dotCMS login screen or go to Maintenance > System Info.

In a clustered environment, you can confirm the running versions of all dotCMS nodes in the Configuration > Network screen:

Automating Updates to Your dotCMS Installation#

Depending on your orchestrator, there are a number of software tools that can be used to automatically update your dotCMS installation. Below are just a few examples of the tools you can use to automate the process.

  • Watchtower: Docker Compose Updater
  • Keel: A Kubernetes Updater
  • Fluxcd: General CI/CD tool — CLI and Kubernetes

Note: In deciding to self-host dotCMS, it is contingent upon you to understand and install and maintain your installation and the tools needed to support it. This list of tools are just by way of example and are not part of dotCMS support.

WatchTower#

Watchtower is a Docker image that can be run in a docker-compose environment that will automatically update the running images as new versions become available. Adding it to your docker-compose is fairly straightforward; below is an example of what that could look like to perform automatic rolling updates at 2:00 a.m.:

watchtower:
 image: containrrr/watchtower
 volumes:
   - /var/run/docker.sock:/var/run/docker.sock
 command: "--schedule "0 0 2 * * * --rolling-restart"

Keel#

Keel is a simple Kubernetes operator to automate image updates. It provides both a webhook that can be used to force an update and a timed job that will scan for newer versions of the dotCMS image.

FluxCD#

If your operation runs GitOps, you can use Fluxcd, digest pinning and git writeback to avoid image drift. It does this by scanning the latest tag on a timed basis. When it finds a new image, it writes the latest tag’s SHA to your manifests/git repo. Below is a snippet of relevant config:

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: podinfo
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: podinfo
  filterTags:
    pattern: '^latest$'
  policy:
    alphabetical: {}
  digestReflectionPolicy: Always
  interval: 10h

On-Demand Update: latest Tag and imagePullPolicy: Always#

While not recommended for production environments, one of the easiest ways to to maintain an up-to-date dotCMS installation in a kubernetes environment is to combine the use of the dotcms/dotcms:latest image with the imagePullPolicy: Always.

The dotcms/dotcms:latest tag points to the most recent dotCMS release and is updated with each new version. By setting the pull policy to Always, dotCMS will automatically fetch the latest image on restart.

With proper health checks in place, you can trigger an update anytime from the dotCMS console:

  1. Go to Maintenance > Tools.
  2. Scroll to the bottom and click Cluster Shutdown.

This initiates a shutdown, and your orchestrator will restart dotCMS using the latest image, applying any required updates automatically.

Best Practices and Strategies#

  • Run Multiple dotCMS replicas (in a cluster) in each Environment
    Running multiple dotCMS nodes in an environment allows you to push updates without a loss of availability.
  • Automate updates on lower environments, delay roll out by a x-days on prod.
    By automating the updates of your lower environment, you can use these environments as canaries, and catch any issues that may arise with a new dotCMS version before it makes it to production. These lower environments also give you a place to ensure that any customizations and plugins function as expected with the new dotCMS versions.
  • Plan to update your prod dotCMS installation every two weeks.
    And more often if you can. Waiting any longer than once a month can introduce breaking changes or version/database incompatibilities during a rolling version update.
  • Version control your manifests or docker-compose files.
    This is critical if you want to roll back; it is important to know which version you were running before the update took place.
  • Backup your dotCMS database before updating or use a managed database service.
    Upgrade tasks update your database schema and data. You can download a complete database dump for your piece of mind by making an API-key authenticated GET call to https://{yourdotcms.com}/api/v1/maintenance/_downloadDb.
    Managing Evergreen On Premise | dotCMS Dev Site