Pega Platform™ supports the client-server model for the Hazelcast service, which provides cluster communication and distributes Pega Platform features across nodes. This optional deployment model introduces independent scalability for both servers and clients in Pega Platform, improving stability for deployments that use a large number of nodes. If you use this configuration, you must configure Hazelcast in client-server mode.

The steps for configuring client-server mode for Hazelcast on Pega Platform include:

1. Preparing for installation
2. Installing and starting the Hazelcast server
3. Enabling encryption for Hazelcast (optional)
4. Configuring Pega nodes with Hazelcast connection details  

Preparing for installation 

Before you begin the install, review the Hazelcast server requirements and prepare Pega Platform.

Hazelcast server requirements

Hazelcast servers must meet the following requirements. Please note that these requirements may change depending on your usage of the data grid and distributed operations.

• Number of servers – Pega minimally requires three Hazelcast servers and will issue an alert should a cluster ever have less than three server nodes. Depending on your deployment, however, more Hazelcast servers may be recommended. For example, if servers and clients are split among different AWS regions or availability zones, we may recommend increasing the number of nodes to protect against network issues between availability zones. 
• Number of cores – Hazelcast recommends a minimum of eight cores per Hazelcast server.
• Server size – Pega recommends a minimum of 4GB RAM for the data grid and general operations.
• Environment requirements – Hazelcast servers must be deployed in a dedicated environment where servers do not compete for resources. 

For additional Hazelcast server requirements, see the documentation for your instance of Hazelcast provided on the Hazelcast website.

Preparing Pega Platform

Configure your database, install or upgrade Pega Platform, and configure the Pega application server. For more information, select the appropriate guide for your system.

• If you are installing Pega Platform, see Installing Pega Platform.
• If you are upgrading Pega Platform, see Stay current with Pega.

Installing and starting the Hazelcast server

You need to install and start Hazelcast for each application server.

1. Make sure that the JAVA_HOME environment variable points to a valid Java directory (JRE or JDK).

2. Move the prcluster_service.war file from the /archives/ directory in the Pega Platform distribution image to the webapps directory of your application server.

3. Start the application server to unpack the prcluster_service.war file.

4. Configure the connection between Hazelcast servers:

   1. On the application server, navigate to the prweb/WEB-INF/classes directory, and then open the prconfig.xml configuration file.
   2. Add the following line to the file:

      <env name="cluster/hazelcast/members" value="ipOfHazelcastServer1:port,ipOfHazelcastServer2:port,ipOfHazelcastServer3:port" />

   3. If the Decision Data Store (DDS) service is enabled or if the system was previously deployed using embedded Hazelcast, you must also change the cluster identification setting:

      <env name="identification/cluster/name" value="prpc" />

   4. Save and close the prconfig.xml configuration file.

5. If your instance of Pega Platform is deployed on Java 11 or later, then open the configuration file for the Hazelcast server and enter the following JVM arguments to allow Hazelcast to run in a modular environment.

   --add-exports java.base/jdk.internal.ref=ALL-UNNAMED
   --add-opens java.base/java.lang=ALL-UNNAMED
   --add-opens java.base/java.nio=ALL-UNNAMED
   --add-opens java.base/sun.nio.ch=ALL-UNNAMED
   --add-opens java.management/sun.management=ALL-UNNAMED
   --add-opens jdk.management/com.ibm.lang.management.internal=ALL-UNNAMED
   --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED
   

6. Start the Hazelcast server.

7. To make sure that the server started successfully, review the topology snapshot in the PegaRULES log files. By default, the system saves the log files in the ../work/Catalina/localhost/prcluster_service/ directory and are accessible only from a terminal window.

Enabling encryption for Hazelcast (optional)

After deploying and starting the Hazelcast server, you can enable file system or database encryption for Hazelcast. Encryption is optional and is useful when compliance rules require encryption of all intracluster communication, such as when working under HIPAA regulations. For instructions on enabling encrypted communication, see Enabling encrypted communication between nodes on Pega Community. 

If you are using Hazelcast Management Center to manage the Hazelcast server, then you also need to set the Hazelcast server to use the default Java truststore to store public certificates for the cluster. For more information, see Deploying Hazelcast Management Center.

Configuring Pega nodes with Hazelcast connection details

Configure connection details by modifying the configuration file used by Pega Platform. 

1. On the Pega application server, navigate to the prweb/WEB-INF/classes directory, and then open the prconfig.xml file.
2. Add the following lines to the file:

   <env name="cluster/clientserver/serveraddress" value="ipOfHazelcastServer1:port,ipOfHazelcastServer2:port,ipOfHazelcastServer3:port" />
   <env name="cluster/clientserver/clientmode" value="true"/>
   <env name="identification/cluster/name" value="prpc" />
   

3. Save and close the file.