Cluster Transport Configuration

Last Updated: Jul 20, 2021
documentation for the dotCMS Content Management System

Hazelcast can be used with dotCMS for both Cluster Transport and/or as a Cache Provider. The following documentation and setup information is required when setting up Hazelcast cache or when integrating Hazelcast with a clustered architecture.

For more information about Hazelcast, please visit the official Hazelcast website.

Configuration Properties

The following parameters in the dotmarketing-config.properties control the behavior of the Hazelcast cache.

  • Note: It is strongly recommended that you make all changes to the dotmarketing-config.properties file through a properties extension file.

Both Manual Clustering and Auto-Clustering configurations are available. The instructions and information on these links are required BEFORE setting up the Hazelcast implementation.

The following configuration property options enable Hazelcast:

Both Embedded (near) and Client (far) cluster transports are configured through “CACHE_INVALIDATION_TRANSPORT_CLASS” property on file “dotmarketing-config.properties” (Embedded is the default):

CACHE_INVALIDATION_TRANSPORT_CLASS=com.dotcms.cache.transport.HazelcastCacheTransportEmbedded (default)
CACHE_INVALIDATION_TRANSPORT_CLASS=com.dotcms.cache.transport.HazelcastCacheTransportClient

Hazelcast Embedded (near) Configuration

To cluster Hazelcast as Embedded (default), use the Hazelcast network configuration on file “hazelcast-embedded.xml”:

<ROOT_DIRECTORY>/dotserver/tomcat/webapps/ROOT/WEB-INF/classes/hazelcast-embedded.xml

This file is now automatically wired by default with corresponding ip-addresses and ports information of the cluster nodes (under/assuming/using TCP protocol). This auto-wiring process may be disabled by setting the following property to false in the dotcms-config-cluster.properties file:

AUTOWIRE_CLUSTER_TRANSPORT=false  (true by default)

WARNING: If disabled, file “hazelcast-embedded.xml” is assumed to have been pre-configured with the required network port and join configuration corresponding to the inherent Hazelcast instance and cluster members dotCMS is to be bound to; for instance:

<hazelcast>
  ...
  <network>
    ...
    <port auto-increment="true" port-count="100">7801</port>
    ...
    <join>
      ...
      <tcp-ip enabled="true">
        <interface>127.0.0.1</interface>
        <member-list>
          ...
          <member>127.0.0.1:7801</member>
          <member>127.0.0.1:7802</member>
          ...
        </member-list>
      </tcp-ip>
      ...
    </join>
    ...
  </network>
  ...
</hazelcast>

Hazelcast Client (far) Configuration

To cluster Hazelcast as Client, use the Hazelcast network configuration on file “hazelcast-client.xml”:

<ROOT_DIRECTORY>/dotserver/tomcat/webapps/ROOT/WEB-INF/classes/hazelcast-client.xml

When using Hazelcast Client as either Cluster Transport or Cache Provider, Hazelcast Client configuration on file “hazelcast-client.xml” is assumed to be pre-configured with the ip-address and port of the corresponding external Hazelcast instance dotCMS is to be bound to; for instance:

<hazelcast-client>
  ...
  <network>
    ...
    <cluster-members>
      ...
      <address>127.0.0.1:7801</address>
      ...
    </cluster-members>
    ...
  </network>
  ...
</hazelcast-client>

Hazelcast Client Setup Steps

Instructions to quickly setup and run dotCMS with Hazelcast Client (against external Hazelcast node/instance) may be summarized as follows:

Setup Hazelcast In-Memory Data Grid:

  1. Download Hazelcast from https://hazelcast.org/download/
  2. Uncompress Hazelcast to directory ““, one Hazelcast node/instance per dotCMS instance in the cluster (on different directories if using nodes on same machine)
  3. Copy contents of file “/webapps/ROOT/WEB-INF/classes/hazelcast-embedded.xml” into file “/bin/hazelcast.xml”
  4. Assign a different port to each and every Hazelcast node/instance on file “/bin/hazelcast.xml”:
    <hazelcast>
...
<network>
...
<port auto-increment="true" port-count="100">7801</port>
...
</network>
...
</hazelcast>
  5. Define the network join configuration on EACH and EVERY Hazelcast node/instance in the file “/bin/hazelcast.xml”. If you are using TCP-IP join schema, this may look like:
    <hazelcast>
...
<network>
...
<join>
  ...
  <tcp-ip enabled="true">
    <interface>127.0.0.1</interface>
    <member-list>
      ...
      <member>127.0.0.1:7801</member>
      <member>127.0.0.1:7802</member>
      ...
    </member-list>
  </tcp-ip>
  ...
</join>
...
</network>
...
</hazelcast>
  6. Configure “hazelcast-client.xml” on each and every dotCMS instance <TOMCAT_LOCATION>/webapps/ROOT/WEB-INF/classes/hazelcast-client.xml as detailed above
  7. Startup each and every Hazelcast node/instance by running “/bin/start.sh”
  8. Startup each and every dotCMS instance! Make sure the associated Hazelcast nodes/instance(s) are up/clustered correctly before running dotCMS.

Cluster Status

Cluster status information on dotCMS backend UI under the “System->Configuration->Network” tab in addition to helpful performance optimization information for distributed cache providers (Hazelcast and Redis).

For more information, see the Hazelcast Cache Provider, Manual Cluster, and Auto-wire Clustering configuration documentation.

On this page