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 5.2.8.3 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 dotcms-config-cluster-ext.properties 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:
AUTOWIRE_CLUSTER_TRANSPORT
AUTOWIRE_CLUSTER_ES
CACHE_FORCE_IPV4
CACHE_PROTOCOL
CACHE_BINDPORT
CACHE_BINDADDRESS
CACHE_TCP_INITIAL_HOSTS
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.
transport.host
transport.tcp.port
discovery.zen.ping.unicast.hosts
http.enabled
http.port
Step 1: Enable Manual Clustering
Set the following two parameters to enable manual cluster configuration:
AUTOWIRE_CLUSTER_TRANSPORT=false
DIST_INDEXATION_ENABLED=true
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:
CACHE_FORCE_IPV4=true
CACHE_PROTOCOL=tcp
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).
CACHE_BINDPORT=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.
CACHE_BINDADDRESS=10.0.1.110
CACHE_TCP_INITIAL_HOSTS=10.0.1.110[7800],10.0.1.111[7800]
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:
auto_expand_replicas=false
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.
