Configuring a cluster
Set up an iGrafx platform cluster with Redis as the shared cache and messaging layer between nodes.
From July 2024, a Redis instance is required to create a cluster.
Prerequisites
- A load balancer — the single entry point (URL) for users. Round-robin balancers work; advanced balancers route to the least-loaded node.
- Redis — the cache and messaging layer between nodes. Install it following the Redis install guide and its hardware requirements; the latest LTS version is recommended. The platform needs read, write, and create permissions plus pub/sub messaging permissions — how you configure these depends on your Redis version. Supporting a production Redis installation is outside iGrafx's scope; work with your IT department, and see the Redis management guide for advanced configuration.
Steps
1. Set up the initial node
Install the first node per the installation guide in non-clustered mode. Once the node has a database, you can sign in, and you've added any users or an LDAP directory, shut it down. Then enable Redis clustering for your installation type — and increase the instance's memory, since clustered nodes store overhead data from other nodes:
- Pre-deployed Tomcat installed via
install_service.bat(Windows) — runmanage_service.bat(add your custom service name as a parameter if you use one, for examplemanage_service.bat myiceservice), go to the Java tab, add the JVM system variable-Digrafx.clustering.redis.enabled=true, click OK, and restart the service. - Pre-deployed Tomcat run manually via
startup.bat— editsetenv.batand setclustering_redis_enabledtotrue. - WAR file — add the system property
-Digrafx.clustering.redis.enabled=trueto your application server.
2. Set the optional Redis variables
Set these if your Redis server isn't on the defaults. Use either the JVM system variable or the environment variable.
| JVM system variable | Environment variable | Default | 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. |
-Digrafx.clustering.redis.username | clustering_redis_username | (none) | Username to connect to your Redis server. |
-Digrafx.clustering.redis.password | clustering_redis_password | (none) | Password to connect to your Redis server. |
-Digrafx.clustering.redis.ssl | igrafx_clustering_redis_ssl | false | Connect to the Redis server over SSL. |
Once these are set, start the node — it's now in cluster mode. Confirm by viewing your cluster status.
3. Add more nodes
Set up each additional node like the first, but instead of a regular installation, copy the dbconfig.xml file from the initial node into the igrafxdata folder of each additional node.
4. Set up the load balancer
The actual load-balancing or failover configuration depends on your goals and IT infrastructure and is outside iGrafx's scope. For a demonstration of the concept, see Configuring a local load balancer.
Troubleshooting
The error messages usually point at the problem.
Connection issues — an unstable connection, firewall settings, an incorrect Redis user, or wrong JVM/environment variables. In the logs:
Caused by: org.springframework.data.redis.RedisConnectionFailureException: Unable to connect to Redis
Caused by: io.lettuce.core.RedisConnectionException: Unable to connect to {ip.address}
Caused by: io.lettuce.core.RedisCommandExecutionException: WRONGPASS invalid username-password pair or user is disabled.
Double-check your JVM/environment variables, then work with your IT team on anything blocking the connection to Redis.
Permission issues — more likely with strict Redis account permissions. In the logs:
Caused by: io.lettuce.core.RedisCommandExecutionException: NOPERM
Check the permissions of the account the platform uses to connect to Redis, and the server permissions on your Redis deployment.