This section includes best practices and guidelines to help you manage on-premises Pega Platform™ environments operating with client-server Hazelcast. 

• Best practices for performing server maintenance
• Upgrading Pega Platform
• Rolling back Hazelcast client-server mode for Pega Platform

Best practices for performing server maintenance

To prevent undesired results, when performing maintenance on Hazelcast servers, use the following best practices:

• Starting servers

  • Ensure to start at least three Hazelcast servers before starting Pega Platform. An alert is sent if less than three servers are available.

  • Ensure that at least one Hazelcast server is in operation for clients to start Pega Platform.

• Shutting down servers

  Ensure that you gracefully shut down all Pega Platform before shutting down the Hazelcast servers.

• Restarting and refreshing servers

  If you need to restart or refresh Pega Platform, you can perform a rolling restart. Perform the restart during low activity times because additional resources are consumed for data repartitioning.

• Increasing Hazelcast cluster capacity

  You can add more Hazelcast servers at any time. For more information about deploying Hazelcast client-server on Pega Platform, see Configuring client-server mode for Hazelcast on Pega Platform.

• Decreasing Hazelcast cluster capacity

  You can remove Hazelcast at any time; however, keeo at least three or more servers in the cluster. An alert is displayed if the number of servers is less than three.

• Recovering after improper shutdown, termination, or node lost

  A full copy of all the data exists across the servers. If one or more of the required three nodes is lost, the other nodes can cover the distributed operations until you restore the node. After you restart the server, the remaining nodes redistribute data to the node to protect against another node loss.

Upgrading Pega Platform

The process for upgrading Pega Platform with Hazelcast depends on the type of upgrade that you want to perform:

• Upgrading from Pega Platform with embedded Hazelcast to Pega Platform with client-server Hazelcast
• Upgrading to major and minor versions of Pega Platform with client-server Hazelcast
• Applying patches to Pega Platform with client-server Hazelcast

Upgrading from Pega Platform with embedded Hazelcast to Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform 8.x with embedded Hazelcast to Pega Platform 8.4 or later with client-server Hazelcast mode enabled, start Hazelcast servers after upgrading the Pega database and application servers and before restarting the Pega nodes.

1. Configure your database, install or upgrade Pega Platform, and then configure the application server. See the appropriate deployment guide for your system on the Deploy Pega Platform page. 
2. Gracefully shut down all Pega nodes in the embedded Hazelcast cluster.
3. Configure client-server mode for Hazelcast on Pega Platform, which involves configuring the connection between Hazelcast servers and changing the cluster identification setting. For instructions, see Configuring client-server mode for Hazelcast on Pega Platform.
4. Restart Pega Platform.

Upgrading to major and minor versions of Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform with Hazelcast client-server, you restart Hazelcast servers after the database is upgraded and before restarting the Pega nodes. 

1. After upgrading the Pega database, gracefully shut down all Pega nodes.
2. Restart the Hazelcast servers.
3. Start the Pega nodes.

To upgrade Pega Platform, see the appropriate deployment guide for your system on the Deploy Pega Platform page. 

Applying patches to Pega Platform with client-server Hazelcast

If you are upgrading Pega Platform with Hazelcast client-server to a patch version of Pega Platform with Hazelcast client-server, no additional upgrade steps apply. You can perform a standard rolling upgrade. Patch releases are available through Digital Software Delivery. To apply a patch to your existing system, see Applying the latest on-premises patch.

Rolling back Hazelcast client-server mode for Pega Platform

If you configured Hazelcast client-server mode for Pega Platform and want to roll back your changes to restore embedded Hazelcast, modify the prconfig.xml file and perform a rolling restart.

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

2. Change the clientmode setting from true to false:

   <env name="cluster/clientserver/clientmode" value="false" />

3. Remove the following line:

   <env name="cluster/clientserver/serveraddress" value="localhost:5701,localhost:5702" />

4. Ensure that database/databases/PegaRULES/defaultSchema is set to the name to which the schema rules were upgraded.
5. Perform a rolling restart of the Pega nodes. For more information, see Performing a rolling upgrade.