⚙️ Hazelcast Setup
Hazelcast provides the distributed, real-time data-processing capabilities used internally by GermainUX. It must be installed and available before the GermainUX services that depend on it are started.
🔖 Supported version
GermainUX supports Hazelcast 5.2.1-slim or later.
Use the Hazelcast version approved for your GermainUX release. Download the appropriate distribution from the Hazelcast download page.
📋 Prerequisites
Before installing Hazelcast, confirm that:
|
Prerequisite |
|---|
|
A compatible Java runtime is installed. |
|
The Hazelcast host is reachable from the applicable GermainUX servers. |
|
Required ports are allowed through host and network firewalls. |
|
The service account can access the Hazelcast installation, configuration, and log directories. |
|
Sufficient memory is available for the Hazelcast JVM. |
|
All cluster members use compatible configurations and Hazelcast versions. |
|
Prerequisite |
|---|
|
A compatible Java runtime is installed. |
|
The Hazelcast host is reachable from the applicable GermainUX servers. |
|
Required ports are allowed through host and network firewalls. |
|
The service account can access the Hazelcast installation, configuration, and log directories. |
|
Sufficient memory is available for the Hazelcast JVM. |
|
All cluster members use compatible configurations and Hazelcast versions. |
📦 Install Hazelcast
Extract the Hazelcast archive to the desired installation directory.
Example locations:
Linux: /opt/hazelcast
Windows: C:\hazelcast
The following examples assume these installation paths.
🚀 Start Hazelcast manually
Manual startup is suitable for development, testing, and initial validation. In production, configure Hazelcast as an operating-system service.
🐧 Linux
Run:
/opt/hazelcast/bin/hz-start
🖥️ Windows
Open Command Prompt and run:
C:\hazelcast\bin\hz-start.bat
Keep the terminal open while Hazelcast is running. Review the console output for startup, configuration, networking, or cluster-discovery errors.
⚙️ Run Hazelcast as a Windows service
GermainUX provides the files required to install Hazelcast as a Windows service.
1️⃣ Copy the service files
Copy the following files from:
{serviceDistroDirectory}\install\hazelcast\
to:
C:\hazelcast\bin\
Required files:
HazelcastService.exe
HazelcastService.xml
2️⃣ Review the service configuration
Before installing the service, review HazelcastService.xml and verify:
|
Item |
|---|
|
The Hazelcast installation path |
|
The Java executable or Java home |
|
JVM memory settings |
|
Startup arguments |
|
Configuration-file location |
|
Log-file location |
|
The Windows service account, when applicable |
|
Item |
|---|
|
The Hazelcast installation path |
|
The Java executable or Java home |
|
JVM memory settings |
|
Startup arguments |
|
Configuration-file location |
|
Log-file location |
|
The Windows service account, when applicable |
3️⃣ Install the service
Open Command Prompt as an administrator, navigate to the Hazelcast bin directory, and run:
cd C:\hazelcast\bin
HazelcastService.exe install
4️⃣ Start the service
Start the Hazelcast Windows service using the Windows Services console or your organization’s service-management process.
Configure its startup type as Automatic if Hazelcast must start when Windows starts.
🏭 Production deployment
For production environments:
|
Recommendation |
|---|
|
Run Hazelcast as an operating-system-managed service. |
|
Configure automatic startup and controlled restart. |
|
Allocate appropriate minimum and maximum JVM heap sizes. |
|
Store configuration and logs in directories accessible to the service account. |
|
Restrict network access to authorized GermainUX and Hazelcast hosts. |
|
Monitor JVM memory, CPU, network connectivity, and cluster membership. |
|
Use consistent Hazelcast versions and configurations across all members. |
|
Back up configuration files before making changes. |
|
Recommendation |
|---|
|
Run Hazelcast as an operating-system-managed service. |
|
Configure automatic startup and controlled restart. |
|
Allocate appropriate minimum and maximum JVM heap sizes. |
|
Store configuration and logs in directories accessible to the service account. |
|
Restrict network access to authorized GermainUX and Hazelcast hosts. |
|
Monitor JVM memory, CPU, network connectivity, and cluster membership. |
|
Use consistent Hazelcast versions and configurations across all members. |
|
Back up configuration files before making changes. |
If multiple Hazelcast instances form a cluster, confirm that every member uses the same:
|
Attribute |
|---|
|
Cluster name |
|
Discovery method |
|
Network configuration |
|
Security configuration |
|
GermainUX-required data structures |
|
Compatible Hazelcast version |
|
Attribute |
|---|
|
Cluster name |
|
Discovery method |
|
Network configuration |
|
Security configuration |
|
GermainUX-required data structures |
|
Compatible Hazelcast version |
⏯️ Start GermainUX
Use the following startup order:
|
Order |
Action |
|---|---|
|
1 |
Start Hazelcast. |
|
2 |
Wait until Hazelcast has initialized and joined the expected cluster. |
|
3 |
Start the remaining GermainUX infrastructure services. |
|
4 |
Start Germain Enterprise. |
|
5 |
Start the Germain nodes. |
|
6 |
Confirm that all components connect without errors. |
|
Order |
Action |
|---|---|
|
1 |
Start Hazelcast. |
|
2 |
Wait until Hazelcast has initialized and joined the expected cluster. |
|
3 |
Start the remaining GermainUX infrastructure services. |
|
4 |
Start Germain Enterprise. |
|
5 |
Start the Germain nodes. |
|
6 |
Confirm that all components connect without errors. |
✅ Validate the installation
After starting Hazelcast, verify that:
|
Check |
|---|
|
The Hazelcast process or Windows service is running. |
|
The logs contain no startup errors. |
|
The expected number of cluster |
|
Check |
|---|
|
The Hazelcast process or Windows service is running. |
|
The logs contain no startup errors. |
|
The expected number of cluster members is reported. |
|
No unexpected Hazelcast instances have joined the cluster. |
|
The Hazelcast port is listening. |
|
GermainUX connects without timeout or connection-refused errors. |
On Linux, check the running process:
ps -ef | grep hazelcast
Check listening ports:
ss -ltnp | grep java
On Windows, check the service:
sc query HazelcastService
The actual service name may differ depending on HazelcastService.xml.
Troubleshooting
⛔ Hazelcast does not start
Check for:
|
Possible cause |
|---|
|
Missing or incompatible Java runtime |
|
Incorrect installation paths |
|
Invalid configuration |
|
Insufficient memory |
|
Port conflicts |
|
Directory-permission errors |
|
Incorrect Windows service configuration |
Review the console output, Hazelcast logs, and Windows Event Viewer when running Hazelcast as a Windows service.
🔗 GermainUX cannot connect
Confirm that:
|
Check |
|---|
|
Hazelcast is running before GermainUX starts. |
|
The configured hostname resolves correctly. |
|
The Hazelcast port is reachable from the GermainUX host. |
|
Firewalls allow the connection. |
|
GermainUX and Hazelcast use matching cluster and security settings. |
|
Hazelcast is listening on an externally reachable interface when components run on different hosts. |
🔍 Cluster members do not discover one another
Verify:
|
Verify |
|---|
|
All members use the same cluster name. |
|
The configured discovery mechanism is correct. |
|
Advertised member addresses are reachable. |
|
Required ports are open between members. |
|
Multicast is supported when multicast discovery is used. |
|
Kubernetes, TCP/IP, or cloud discovery settings are consistent across members. |
|
No version or configuration mismatch prevents members from joining. |
🔧 Windows service does not start
Verify the paths and arguments in:
C:\hazelcast\bin\HazelcastService.xml
Also confirm that the Windows service account:
|
Permission |
|---|
|
Can execute Java and Hazelcast |
|
Can read the configuration files |
|
Can write to the log directory |
|
Has permission to run as a service |
Source: Hazelcast Setup.
Service: Enterprise
Feature Availability: 2024.1