Skip to main content
ServiceEnterprise
Availability2024.1

Install the services on Windows

Setup with WinSW

Configure the services

Edit YAML config files

Validate the deployment

Check services are running

Troubleshooting

Resolve service startup problems
GermainUX Services GermainUX Services process telemetry in real time to support alerting, analytics, session tracking, data aggregation, storage, insights, and automated actions. This guide explains how to install and configure these services from the GermainUX Service distribution.

​
Prerequisites

Before installing the services, confirm that:
  • The GermainUX datastore is installed and accessible.
  • Germain Enterprise and its required infrastructure components are installed.
  • A compatible Java runtime is available.
  • The required .NET Framework is installed when deploying the services on Windows.
  • The service account can access the installation, configuration, and log directories.
  • Required network connections are allowed.
  • The GermainUX license has been deployed.

​
Extract the service distribution

Extract the GermainUX Service distribution to the desired installation directory. Example:
In this guide, SERVICES_HOME refers to that directory. If the supplied scripts require the APM_HOME environment variable, set it to the same location.

​
Linux

To make these variables persistent, configure them for the account under which the GermainUX services run.

​
Windows

Set:
You can configure these variables through Windows System Properties or your organization’s service-deployment process.

​
GermainUX services

The distribution includes the following services: The configuration files are located under:

​
Install the services on Windows

The GermainUX Service distribution uses WinSW to install and manage the services on Windows.

​
1 Select the correct .NET Framework version

Open:
Run the script corresponding to the highest applicable .NET Framework version installed on the server: If necessary, use Microsoft’s instructions to determine the installed .NET Framework version. Open Command Prompt as an administrator before running the selected script.

​
2. Review the service definitions

The SERVICES_HOME\bin directory contains an XML definition for each service. Before installation, verify:
  • Java executable or Java home
  • Service installation directory
  • YAML configuration-file path
  • JVM memory settings
  • Log directory
  • Startup arguments
  • Service name and display name
  • Windows service account, when applicable

​
3. Install each service

From an administrative Command Prompt, navigate to:
Install each required service:
Replace <service-name> with the executable name provided for the service. Repeat the command for every GermainUX service required by the deployment.

​
4. Confirm that the services were installed

Open the Windows Services console:
Verify that each installed GermainUX service appears in the service list. Configure the startup type according to your deployment requirements. Production services are normally configured to start automatically.

​
Configure the services

Each service is configured through its YAML file under:
Before starting a service, review its configuration and verify:
  • ZooKeeper connection
  • Kafka or legacy ActiveMQ connection, depending on the GermainUX release
  • Hazelcast connection
  • Datastore connection
  • Environment or configuration-root name
  • Network ports and advertised hostnames
  • Authentication and TLS settings
  • Log level and output directory
  • Service-specific processing settings
Use spaces—not tabs—for YAML indentation. Incorrect indentation can prevent a service from starting or cause settings to be interpreted incorrectly. Back up each configuration file before modifying it.

​
Configure JVM memory

Java runtime options, including minimum and maximum heap sizes, can be adjusted in the corresponding service XML file under:
Typical JVM memory options include:
For example:
Choose values according to the service workload and available server memory. Do not allocate the entire host memory to the Java services; reserve sufficient capacity for the operating system, Tomcat, infrastructure components, and the datastore when colocated. Restart the affected service after changing its XML definition or JVM settings.

​
Startup order

Start the GermainUX environment in the following order:
1

Start the datastore

2

Start ZooKeeper

3

Start Kafka—or ActiveMQ for legacy GermainUX releases

4

Start Hazelcast

5

Start Germain Enterprise on Tomcat

6

Start the GermainUX services

7

Start the Germain nodes and other monitoring components

8

Verify that data is being collected and processed

Wait for each infrastructure component to become available before starting the services that depend on it.

​
Shutdown order

Use the reverse order when shutting down the environment:
1

Stop monitoring components and Germain nodes

2

Stop the GermainUX services

3

Stop Germain Enterprise

4

Stop Hazelcast

5

Stop Kafka or legacy ActiveMQ

6

Stop ZooKeeper

7

Stop the datastore, when required

A controlled shutdown reduces the risk of interrupted processing or incomplete writes.

​
Validate the deployment

After starting the services, confirm that:
  • Every required Windows service is running.
  • No service enters a repeated restart cycle.
  • The service logs contain no configuration or connection errors.
  • Each service connects to ZooKeeper, Hazelcast, Kafka or ActiveMQ, and the datastore as required.
  • Incoming telemetry is stored successfully.
  • Real-time metrics and aggregations are generated.
  • User sessions are processed.
  • Alerts and automated actions execute as expected.
  • Data appears in the GermainUX Workspace.
Check a Windows service from the command line:
You can also review its state through services.msc.

​
Troubleshooting

​
A service does not start

Check for:
  • Missing or incompatible Java or .NET Framework
  • Incorrect paths in the service XML definition
  • Invalid YAML syntax
  • Insufficient JVM memory
  • A port conflict
  • Incorrect file permissions
  • An unavailable infrastructure dependency
  • An invalid service account or password
Review the service log and Windows Event Viewer for the first relevant error.

​
A service starts and then stops

This usually indicates an application-level startup failure. Verify:
  • Configuration-file paths
  • YAML formatting
  • ZooKeeper configuration root
  • Datastore connectivity
  • Kafka or ActiveMQ connectivity
  • Hazelcast availability
  • Authentication credentials
  • TLS certificates and truststores
Running the underlying Java process interactively may provide a more detailed startup error than the Windows service wrapper.

​
Configuration changes are not applied

After changing a YAML file or service XML definition:
1

Confirm that you edited the file used by the installed service

2

Validate the YAML syntax

3

Restart the affected service

4

Review the startup log to confirm that the expected configuration was loaded

​
A service cannot write logs

Confirm that:
  • The log directory exists.
  • The Windows service account has write permission.
  • The disk has sufficient free space.
  • Antivirus or endpoint-security software is not blocking file creation.
  • Log rotation is configured to prevent unbounded disk usage.

​
Next step

After all required services are installed and running, initialize the GermainUX configuration using the GermainUX Initial Configuration procedure. Source: GermainUX Services.

​
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.