Engine Deployment

⚙️ GermainUX Engine Deployment

This guide explains how to deploy the GermainUX Engine on Windows, Linux, or Docker.

The GermainUX Engine runs monitoring, diagnostic, and automation components close to the systems being monitored. Each Engine host includes an Engine Manager, which connects to Germain Enterprise and controls one or more Engine instances.

🧭 Choose a deployment method

For production, run the Engine as an operating-system service or managed container so it starts automatically and can be monitored.

📋 Prerequisites

Before deploying an Engine, confirm that:

📏 Reference sizing

The documented reference sizing is:

These are planning estimates. Actual requirements depend on:

Monitor actual resource consumption and resize the Engine or distribute its workload when necessary.

📡 Network connectivity

The Engine must be able to connect to Germain Enterprise.

Typical HTTP ports include:

80
8080

For HTTPS, the actual port depends on your reverse proxy, load balancer, or Tomcat configuration.

Legacy GermainUX releases using ActiveMQ may also require:

61616

ActiveMQ applies only to GermainUX releases earlier than 2024. Use the messaging and network requirements supplied for your installed GermainUX version.

Also confirm that the Engine can reach the applications, databases, files, APIs, and servers it will monitor.

📂 Install Java

Install the Java version approved for your GermainUX release.

Verify it:

java -version

Verify JAVA_HOME.

Windows Command Prompt:

echo %JAVA_HOME%

PowerShell:

echo $env:JAVA_HOME

Linux:

echo $JAVA_HOME

If the wrong Java version is returned, review JAVA_HOME, the system PATH, the service configuration, and any other installed Java versions.

⬇️ Download the Engine

The current Windows distributions are available from the GermainUX Workspace:

1. Sign in to the Workspace.

2. Open Wizards.

   

3. Select Engine.

4. Download the appropriate package:

   • Windows Installer

   • Windows Binary

     

For Linux or Docker deployments, use the Engine distribution provided for your GermainUX release.

📁 Engine installation directory

Create or select the directory where the Engine will be installed.

Examples:

Windows: D:\Germain\engines
Linux:   /opt/germain/engines

This guide refers to that directory as:

ENGINE_HOME

Extract the Engine distribution into ENGINE_HOME.

📦 Install database drivers

If the Engine will monitor a database, copy the applicable JDBC driver into:

ENGINE_HOME/lib

Examples include:

MySQL:  mysql-connector-j-<version>.jar
Oracle: ojdbc<version>.jar

Use a JDBC driver compatible with the monitored database, Java runtime, and GermainUX version. Do not copy obsolete drivers from older deployments without reviewing their compatibility and security status.

🔗 Configure the Engine Manager connection

Open:

ENGINE_HOME/config/germain-bootstrap.properties

Configure the following properties as applicable.

🌐 Germain Enterprise URL

germain.bootstrap.configService=<germain-enterprise-url>

Example:

germain.bootstrap.configService=https://germain.example.com

🔑 Authentication

germain.bootstrap.configUser=<username>
germain.bootstrap.configPassword=<password>

Use a dedicated service account for production. Restrict access to this file because it may contain credentials.

💻 Monitoring node

germain.bootstrap.node=

Two options are available:

• Leave the value empty to let the Engine Manager register a new node automatically. This is preferred.

• Enter the hostname of an existing node under germain.apm.monitoringNode.

  

📨 Messaging

Older Engine distributions may contain:

germain.activemq.url=<hostname>:61616

Configure this only for a legacy GermainUX release that uses ActiveMQ. For GermainUX 2024.2 or later, use the transport configuration provided with the current Engine distribution.

👀 Run the Engine in the foreground

Foreground execution is useful for initial validation because startup errors appear directly in the terminal.

It is not recommended for routine production operation.

😎 Windows

Open:

ENGINE_HOME\bin\startEngine.bat

Review the JVM memory settings, then open Command Prompt and run:

cd /d <ENGINE_HOME>
bin\startEngine.bat

Keep the command window open while the Engine runs.

🐧 Linux

Open:

ENGINE_HOME/bin/startEngine.sh

Review its JVM memory settings, then run:

cd "$ENGINE_HOME"
./bin/startEngine.sh

Run the Engine using a dedicated operating-system account. Root privileges should not be required unless a specific monitoring component needs privileged access and that access has been approved.

🪟 Deploy with the Windows installer

1️⃣ 1. Run the installer

Run the downloaded Engine .msi file.

2️⃣ 2. Configure the Germain Enterprise address

Enter the Germain Enterprise URL.

Example:

https://germain.example.com

3️⃣ 3. Configure the proxy

If the Engine reaches Germain Enterprise through a proxy, enter:

• Proxy protocol

• Proxy hostname

• Proxy port

Leave these fields empty when no proxy is required.

4️⃣ 4. Select the installation directory

Enter the desired installation path and continue.

✅ 5. Complete the installation

Select Install, wait for the installation to finish, and then select Finish.

The installer registers the Engine Manager as a Windows service.

⚙️ Silent Windows installation

Use the silent installer to automate deployment.

Example:

msiexec.exe /QN /I "C:\Install\GermainAPMEngines.msi" ^
  INSTALLFOLDER="C:\germain\engines" ^
  APM_SERVICEURL="https://germain.example.com"

With an HTTP proxy:

msiexec.exe /QN /I "C:\Install\GermainAPMEngines.msi" ^
  INSTALLFOLDER="C:\germain\engines" ^
  APM_SERVICEURL="https://germain.example.com" ^
  PROX="http" ^
  APM_HTTPPROXY="http://proxy.example.com:8080"

Because /QN suppresses the interface, installation errors may not be visible. Capture an MSI log:

msiexec.exe /QN /I "C:\Install\GermainAPMEngines.msi" ^
  /L*v "C:\Install\GermainEngine-install.log" ^
  INSTALLFOLDER="C:\germain\engines" ^
  APM_SERVICEURL="https://germain.example.com"

Review the log if the service is not installed successfully.

📁 Deploy the Windows binary as a service

Use this method when you need direct control over the Engine files and Windows service definition.

1️⃣ 1. Extract the binary

Extract the downloaded archive and place its engines directory in the desired location.

That directory becomes ENGINE_HOME.

🔧 2. Configure JVM memory

Open:

ENGINE_HOME\bin\GermainEngineStandalone.xml

Review the Java executable, working directory, Engine name, log path, and JVM options.

Typical options include:

<argument>-Xms256m</argument>
<argument>-Xmx1024m</argument>
<argument>-XX:+CrashOnOutOfMemoryError</argument>
<argument>-Dgermain.engine=standalone</argument>

⚙️ 3. Configure the service wrapper

Open Command Prompt as an administrator and navigate to:

cd /d <ENGINE_HOME>\bin\WinSW

Run the script matching the installed .NET Framework:

set-dotnet-2.bat
set-dotnet-4.bat
set-dotnet-461.bat

Choose the highest applicable version.

4️⃣ 4. Install the service

Navigate back to the bin directory:

cd ..
GermainEngineStandalone.exe install

✅ 5. Verify the service

Open:

services.msc

Confirm that the Germain Engine service appears and starts successfully.

🐧 Install as a Linux systemd service

Modern Linux distributions should use systemd.

Review the service definition supplied under:

ENGINE_HOME/bin/germain-engine.service

Ensure that it contains:

• A dedicated service account

• The correct ENGINE_HOME

• The correct Java executable

• The correct startup command

• Restart behavior

• Required environment variables

• Appropriate file permissions

A representative service definition is:

[Unit]
Description=GermainUX Engine
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=germain
WorkingDirectory=/opt/germain/engines
Environment="ENGINE_HOME=/opt/germain/engines"
ExecStart=/opt/germain/engines/bin/startEngine.sh
Restart=on-failure
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Copy the reviewed service file:

sudo cp "$ENGINE_HOME/bin/germain-engine.service" \
  /etc/systemd/system/germain-engine.service

Reload systemd:

sudo systemctl daemon-reload

Enable automatic startup:

sudo systemctl enable germain-engine.service

Start the service:

sudo systemctl start germain-engine.service

Check its status:

sudo systemctl status germain-engine.service

Use the supplied service definition when it differs from the representative example above.

⚙️ Install on a System V distribution

For older distributions using System V, follow the service procedure supplied with the Engine package.

A legacy deployment may create a link under:

/etc/init.d/germain-engine

The service can then be managed with:

sudo service germain-engine start
sudo service germain-engine stop
sudo service germain-engine restart

Prefer systemd on distributions that support it.

🐳 Deploy with Docker Compose

1️⃣ 1. Extract the Docker package

Extract the GermainUX Docker files.

Example:

/opt/germain

2️⃣ 2. Create the Docker network

docker network create germain

If the network already exists, verify that the supplied Compose files use it.

3️⃣ 3. Start the required infrastructure

cd /opt/germain
docker-compose -f compose/apm-infrastructure.yaml up -d --force-recreate

Wait until the required infrastructure containers are ready.

⚙️ 4. Configure GermainUX

Review:

cd /opt/germain/config
nano bootstrap.zk

Configure the required database, SMTP, infrastructure, and environment-specific settings.

Protect credentials using your organization’s secret-management process.

🚀 5. Start the GermainUX Services

cd /opt/germain
docker-compose -f compose/apm-services.yaml up -d --force-recreate

⚙️ 6. Configure the Engine

Open:

cd /opt/germain/config
nano engine.env

Configure the Germain Enterprise URL and other Engine settings.

▶️ 7. Start the Engines

cd /opt/germain
docker-compose -f compose/apm-engines.yaml up -d --force-recreate

✅ 8. Validate the containers

docker-compose -f compose/apm-engines.yaml ps
docker-compose -f compose/apm-engines.yaml logs

Confirm that the Engine Manager connects successfully and waits for authorization when required.

🔒 Authorize the Engine Manager

A newly deployed Engine Manager may need approval before it can finish loading.

In the GermainUX Workspace:

1. Open Germain > State.

2. Select Nodes.

3. Search for the new node.

4. Select the lock in the Sessions column.

5. Select Confirm.

The Engine Manager retries authorization periodically. After approval, the log should report a successful authorization and continue initialization.

The default Engine is normally named:

standalone

You can rename it or create additional Engines for the node.

📋 Validate the deployment

After installation, confirm that:

Review:

ENGINE_HOME/logs/EngineManager.log

A successful startup includes:

Started EngineManagerApplication in <duration> seconds

⬆️ Upgrades

The Engine Manager automatically restarts after an Engine upgrade.

After upgrading, verify that:

• The expected Engine version is running.

• The Engine Manager restarted successfully.

• The node remains authorized.

• The expected Engines are enabled.

• Custom JDBC drivers remain available.

• Monitoring components resumed execution.

• No Java, network, messaging, or configuration errors appear.