Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Configuring client-server mode for Hazelcast on Pega Platform

Updated on April 27, 2023

This content applies only to On-premises and Client-managed cloud environments

Important: This older client-server model deployment of a Hazelcast service described below was deprecated in Pega Platform™ 8.8. For new deployments that use Pega Platform 8.8 and Pega Infinity™ '23, Pega recommends that you deploy a Hazelcast service using the new client/server model. For details, see Deploying and connecting to your managed Hazelcast service. This older client-server model deployment of a Hazelcast service described below will not be supported in Pega Infinity '24.

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.

Note: The Hazelcast client-server model is intended for select environments running Pega Platform 8.4 or later across a large number of nodes and should be deployed only when directed to by Global Client Support.

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  
Note: Certain considerations apply for performing maintenance on Pega Platform environments operating with client-server Hazelcast. See Managing Hazelcast client-server mode for Pega Platform for more information.

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.

  • Do not deploy the Pega Platform and Hazelcast (either a WAR or EAR file) on the same application server.
  • Make sure you install the required JVM arguments on the Pega Platform server if you are using Java 11 or later, as documented in the install and upgrade guides.
  • Do not start Pega Platform until the Hazelcast servers are started. If you are upgrading to Hazelcast client-server, gracefully shut down all Pega nodes before installing and starting the Hazelcast server.
What to do next: Install and start the Hazlecast server. See the next section, Installing and starting the Hazelcast server

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/
  1. Start the Hazelcast server.
Notice: If your system is running Pega Platform 8.8.2, the server starts up without error messages; if you are running version 8.8.0 or 8.8.1, you can see a NullPointerException error in a console session or in PegaCLUSTER logs during the start up process, which is safe to ignore.
  1. 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.
What to do next: If you are using encryption, then you must also enable encryption for Hazelcast. See the next section, Enabling encryption for Hazelcast (optional).  If you are not using encryption, then you can configure the Pega nodes with Hazelcast connection details. See the section, Configuring Pega nodes with Hazelcast connection details

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.

What to do next: Configure the Pega nodes with Hazelcast connection details. See the next section, Configuring Pega nodes with Hazelcast connection details

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.
What to do next: You can now start Pega Platform or deploy Hazelcast Management Center if you are using it. For more information about the Hazelcast Management Center, see Deploying Hazelcast Management Center.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us