Germain UX Services

⚙️ 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:

📁 Extract the service distribution

Extract the GermainUX Service distribution to the desired installation directory.

Example:

Linux:   /opt/germainapm
Windows: C:\germainapm

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

export APM_HOME=/opt/germainapm
export SERVICES_HOME=/opt/germainapm

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

💻 Windows

Set:

APM_HOME=C:\germainapm
SERVICES_HOME=C:\germainapm

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:

SERVICES_HOME/config

🪟 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:

SERVICES_HOME\bin\WinSW

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:

🛠️ 3. Install each service

From an administrative Command Prompt, navigate to:

cd C:\germainapm\bin

Install each required service:

<service-name>.exe install

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:

services.msc

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:

SERVICES_HOME/config

Before starting a service, review its configuration and verify:

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:

SERVICES_HOME/bin

Typical JVM memory options include:

-Xms<size>
-Xmx<size>

For example:

-Xms1g
-Xmx4g

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:

Check a Windows service from the command line:

sc query "<service-name>"

You can also review its state through services.msc.

🔧 Troubleshooting

❌ A service does not start

Check for:

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:

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:

⏭️ Next step

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

Source: GermainUX Services.