Manual Cluster Configuration documentation for the dotCMS Content Management System

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:


Next, define the local port and network address for ElasticSearch to bind to.


  • Use the default port (9301) on all servers, unless there are conditions that dictate otherwise.

Next, configure the list of index cluster members. The index cluster list is in address:port notation, comma-separated with no spaces.

Note: The notation for the index cluster list uses a slightly different syntax from the cluster cache invalidation properties (above).,

Number of Replicas for the Content Index

You must set the number of replicas for the ElasticSearch index. Setting ES_INDEX_REPLICAS to a specific integer (not a range), AND setting AUTOWIRE_CLUSTER_ES=false enables the manual management of replicas via the dotCMS UI. This is not default behavior and both of these properties will need to be configured to enable manual ES replica management.

For information on the ES_INDEX_REPLICAS property configuration, and automated VS manual replica management, please see the Auto-Cluster Configuration documentation.

Note that setting the proper number of replicas for the ElasticSearch index can be confusing:

  • It is important to understand that the number of replicas does not equal the number of servers in your cluster.
    • The number of index replicas in a cluster indicates the number of EXTRA copies of the index beyond the first primary copy.
  • In order to ensure that the index is available on each server (for best performance and availability), the number of replicas should be n-1, where n is the number of servers in the cluster.
    • This means that there is the original index entry on one server and 1 replica on each additional server, so each server has a copy of each index.
    • For example, if you are running a two node cluster then you should have your ElasticSearch replicas set to 1, and if you are running a 3 node cluster then you should have your ElasticSearch replicas set to 2. A 5-node cluster would have 4 replicas configured:

For information on the automated addition of replicas, please see the Auto-Cluster Configuration documentation.

ElasticSearch HTTP API

The direct ElasticSearch API can be exposed in dotCMS using the following parameters for management or debugging purposes.


  • This feature is optional, and is not required for dotCMS operation.
  • The ElasticSearch API has NO AUTHENTICATION built-in, and will provide full access to query, modify, and destroy all dotCMS indexes to anyone who can access it at the network level.
    • When this is enabled, access should always be strictly controlled at the network level.

The following parameters enable the ElasticSearch HTTP API and set the port it runs on:


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.