Skip to main content
ServiceEnterprise
Availability2024.1

Prerequisites

Checks before installing

Run Hazelcast as a Windows service

Install with bundled service files

Production deployment

Cluster members must match

Troubleshooting

Fix cluster and startup issues
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:
  • 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.
  • 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:
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:

​
Windows

Open Command Prompt and run:
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:
to:
Required files:

​
2 Review the service configuration

Before installing the service, review HazelcastService.xml and verify:
  • 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
  • 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:

​
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:
  • 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.
  • 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:
  • Cluster name
  • Discovery method
  • Network configuration
  • Security configuration
  • GermainUX-required data structures
  • Compatible Hazelcast version
  • Cluster name
  • Discovery method
  • Network configuration
  • Security configuration
  • GermainUX-required data structures
  • Compatible Hazelcast version

​
Start GermainUX

Use the following startup order:

​
Validate the installation

After starting Hazelcast, verify that:
  • The Hazelcast process or Windows service is running.
  • The logs contain no startup errors.
  • The expected number of cluster
  • 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:
Check listening ports:
On Windows, check the service:
The actual service name may differ depending on HazelcastService.xml.

​
Troubleshooting

​
Hazelcast does not start

Check for:
  • 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:
  • 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:
  • 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:
Also confirm that the Windows service account:
  • 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.

​
Get Help

Contact GermainUX Support

The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

Can't find what you need?

Search all GermainUX docs with Ctrl + K, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.