Manual Cluster Configuration

Last Updated: May 12, 2021
documentation for the dotCMS Content Management System

Manual configuration should only be used if (Auto Clustering) [auto-clustering] doesn't work for your situation. The most common reasons to need manual clustering are having a external ES in and before or having an external cache optimizer. To manually enable clustering in dotCMS, you must manually edit the cluster properties file. The following configuration steps are required to manually configure clustering behavior.

Note: You must complete all installations steps in the Cluster Configuration document before performing any of these installation steps.

Configuration Files and Properties

Numerous configuration properties affect clustering, but only a small subset are required for manual cluster configuration in most situations. If you believe that your specific environment requires additional configuration beyond these, please contact dotCMS Support to ensure that they will work as intended.

Configuration changes should be made and deployed to the file found in the /plugins/com.dotcms.config/conf/ directory. You can download an example of the configuration plugin files for a cluster with two servers.

The following parameters are required for manual cluster configuration:


In addition the elasticsearch.yml should also be over-ridden via ROOT plugin configuration using the elasticsearch-override.yml in the /WEB-INF/elasticsearch/config directory.

Step 1: Enable Manual Clustering

Set the following two parameters to enable manual cluster configuration:


Step 2: Clustered Cache Invalidation

The cluster cache invalidation component ensures that the dotCMS cache is kept in sync across the cluster.

First, set the following two parameters to enable the proper networking support for cluster cache invalidation:


Next, specify which port the clustered cache invalidation service will run on. This port will need to be accessible from all servers in the cluster.

Recommendations (unless there are environmental constraints dictating otherwise):

  • Use the same port number on all servers in the cluster.
  • Use the default port (7800).

Next, configure the cluster cache invalidation with both the intended local network address for this server, and a list of all the addresses and cache ports for all servers in the cluster. The cache server list is specified in address[port] notation, comma-separated with no spaces.


Step 3: Index (ElasticSearch) Cluster

This step configures the index clustering.

First, disable automatic index replica management. This is usually undesirable when using manual cluster configuration, as manual management provides more deterministic behavior:


Verifying Your Configuration

After completing all configuration and starting all the nodes in your cluster, please see the Testing Your Cluster section in the Cluster Configuration documentation for steps to verify the proper operation of your cluster.

On this page


We Dig Feedback

Selected excerpt: