Configuring a cluster

Starting July 2024, a Redis instance will be required to create a cluster.

Clustering is an optional feature for Process Design.

Requirements

Load Balancer

To make use of a clustered environment for any reason, a Load Balancer is a requirement. The Load Balancer will make sure that end users only have one point of entry (URL) to access the application. While common load balancers simply redirect users via a round-robin behavior, advanced load balancers can determine the current load of the target systems and forward users to the least used resource.

Redis

Redis functions as an intermediary cache and messaging layer connecting nodes within a cluster. Installation of Redis should be executed following their provided guide (making sure to take note of the minimum required specifications). While Process Design does work with older versions of Redis we recommend using the latest LTS version of Redis.

After installation, depending on your Redis configuration, there are some considerations to take. Process Design needs read, write, and create permissions. Additionally, permissions for utilizing the pub/sub messaging functionalities. The way in which you configure these is highly dependent on which version of Redis you are using.

Support for a production Redis installation is out of the scope of the iGrafx software installation documentation. We recommend working with your IT department to install Redis. Each installation will be dependent on your network, IT infrastructure and additional factors. Here is a helpful link to official Redis documentation for advanced configuration of a Redis server:

Advanced setup guide for Redis can be found here: https://redis.io/docs/management/

Set up initial node

The first node is installed according to the normal Installation Guide in non-clustered mode initially. Once you have set up your instance with a database, have validated that you can log in and potentially added users or an LDAP directory, shut down the node again. Depending on the installation type, the following steps are necessary. When performing them, it is strongly recommended to increase the memory of your instance, as clustered environments tend to require more memory due to an overhead in data stored from other nodes.

Predeployed Tomcat set up via install_service.bat on Windows
- Run manage_service.bat (if you are using a custom service name, you will need to add that as a parameter, i.e. manage_service.bat myiceservice)
- Go to the Java Tab and add a new JVM system variable -Digrafx.clustering.redis.enabled=true
- Press OK to save your settings
- Restart your service
Predeployed Tomcat run manually via startup.bat
- Edit the file setenv.bat and make sure that the variable clustering_redis_enabled is set to true
WAR file
- Add a new system property to your respective application server: -Digrafx.clustering.redis.enabled=true

Optional Variables

JVM System Variable	Environment Variable	Default Value	Description
`-Digrafx.clustering.redis.host`	`clustering_redis_host`	localhost	Host URL of your Redis server.
`-Digrafx.clustering.redis.port`	`clustering_redis_port`	6379	Port to connect to your Redis server on.
`-Digrafx.clustering.redis.username`	`clustering_redis_username`		Username to connect to your Redis server.
`-Digrafx.clustering.redis.password`	`clustering_redis_password`		Password to connect to your Redis server.
`-Digrafx.clustering.redis.ssl`	`igrafx_clustering_redis_ssl`	false	Enable connection to Redis server using SSL.

Once above variables are configured you are ready to start your node, and it should now be in cluster mode.

Confirming your cluster is setup

To confirm your cluster is working properly you should view your cluster status: Clustering | Viewing-your-Cluster-Status. If you see the information listed there, you are ready to enjoy the benefits of running Process Design in a cluster.

Set up additional nodes

Additional nodes can be set up by following the above protocol for the initial node, but instead of doing the installation like regular, make sure to copy the dbconfig.xml file from your initial node into the igrafxdata folder of any additional nodes.

Set up Load Balancer or Fail Over configuration

The actual load balancing or fail over configuration requires profound knowledge of your goals and IT infrastructure and is beyond the scope of the iGrafx Product documentation. But for demonstration purposes about the concept behind a load balanced setup you should see the page: Configuring a local load balancer.

Troubleshooting

We have found the error messages to provide a good idea as to what may be going wrong. Here are some common issues and some solutions for them.

Connection Issues

These types of issues can occur for many reasons such as an unstable internet connection, incorrect firewall settings, incorrect Redis user configuration, incorrect JVM/Environment variables, and more. They can be seen in the error logs as:

CODE

Caused by: org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis

CODE

Caused by: io.lettuce.core.RedisConnectionException: Unable to connect to {ip.address}

CODE

Caused by: io.lettuce.core.RedisCommandExecutionException: WRONGPASS invalid username-password pair or user is disabled.

To fix these we recommend double checking your JVM/Environment variables and ensure all the information is correct. If those are correct you should follow up with your IT team and determine if there is something preventing a connection from Process Design to Redis.

Permission Issues

These are more likely to happen if your deployment of Redis has strict permissions setup for accounts (if using accounts). These errors can show up in the logs as:

CODE

Caused by: io.lettuce.core.RedisCommandExecutionException: NOPERM

We recommend double checking your permissions for the account that Process Design is using to connect to Redis. As well as the server permissions with your Redis deployment.