> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Engine Deployment

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

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)

Availability
8.6.0 or later

> [card] [Silent Windows installation](#silent-windows-installation)
>
> Automate MSI installs

> [card] [Deploy the Windows binary as a service](#deploy-the-windows-binary-as-a-service)
>
> Direct control over service

> [card] [Install as a Linux systemd service](#install-as-a-linux-systemd-service)
>
> Service definition for systemd

> [card] [Deploy with Docker Compose](#deploy-with-docker-compose)
>
> Containerized 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

| Method | Recommended use |
| - | - |
| Windows installer | Standard Windows service deployment |
| Windows silent installer | Automated deployment to multiple Windows hosts |
| Windows binary | Customized Windows service deployment |
| Linux `systemd` service | Standard production deployment on modern Linux |
| Linux System V service | Older Linux distributions |
| Foreground process | Initial validation and troubleshooting |
| Docker Compose | Containerized environments |

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:

* A GermainUX-approved Java version is installed.
* `JAVA_HOME` points to the correct Java installation.
* The host can reach Germain Enterprise.
* Required network ports are open.
* Proxy details are available when direct connectivity is not permitted.
* The host can reach every system the Engine will monitor.

> [accordion] Show all 10
>
> * Required JDBC drivers are available for database monitoring.
> * The Engine service account can access the required files, services, commands, and endpoints.
> * Docker Compose 1.29 or later is installed for Docker deployment.
> * Sufficient CPU, memory, and disk capacity are available.

## Reference sizing

The documented reference sizing is:

| Workload | CPU | Memory | Local storage |
| - | - | - | - |
| Low scale—up to 1 million units per day | Approximately 5% | 2 GB | 500 MB–30 GB |
| Medium to large—1 to 100 million units per day | Approximately 5% | 2 GB | 500 MB–30 GB |
| Big data—more than 100 million units per day | Approximately 5% | 2 GB | 500 MB–30 GB |

These are planning estimates. Actual requirements depend on:

* Number and type of monitoring components
* Component execution frequency
* Log and telemetry volume
* Local buffering requirements
* Synthetic transactions
* Database queries
* Automation workload
* Local state-store size

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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
java -version
```

Verify `JAVA_HOME`.

Windows Command Prompt:

```text theme={null}
echo %JAVA_HOME%
```

PowerShell:

```text theme={null}
echo $env:JAVA_HOME
```

Linux:

```text theme={null}
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**.

   ![Engine Wizard](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/223165690-5336057a-8035-44f5-9892-1b9a77bb0cf8.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=b9eefaaea079bc7e356c6fbd91fc7610)

   Engine Wizard - GermainUX
3. Select **Engine**.
4. Download the appropriate package:
   * **Windows Installer**
   * **Windows Binary**

     ![Download link for GermainUX Engine](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/223165815-bbafe17a-aa05-493c-8e4b-9b4bd0c22dcb.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=b124ac05ab48f0aa03dda99a8f438b17)

     Download link for GermainUX Engine

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:

```text theme={null}
Windows: D:\Germain\engines
Linux:   /opt/germain/engines
```

This guide refers to that directory as:

```text theme={null}
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:

```text theme={null}
ENGINE_HOME/lib
```

Examples include:

```text theme={null}
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:

```text theme={null}
ENGINE_HOME/config/germain-bootstrap.properties
```

Configure the following properties as applicable.

### Germain Enterprise URL

```text theme={null}
germain.bootstrap.configService=<germain-enterprise-url>
```

Example:

```text theme={null}
germain.bootstrap.configService=https://germain.example.com
```

### Authentication

```text theme={null}
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

```text theme={null}
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`.

  ![Authorize Node (Engine Manager)](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image-20230221-221625.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=fdd9a77ee80a9acec49b03d6c66d3a26)

  Authorize Node (Engine Manager)

### Messaging

Older Engine distributions may contain:

```text theme={null}
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:

```text theme={null}
ENGINE_HOME\bin\startEngine.bat
```

![Engine Deployment: Windows](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image-20200320-181906.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=51fe9cab461d4123cb3cb739e8d4af89)

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

```text theme={null}
cd /d <ENGINE_HOME>
bin\startEngine.bat
```

Keep the command window open while the Engine runs.

![Engine Deployment: Windows, image 2](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image2018-6-1_8-12-26.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=712990322a9478100b9089a923a43506)

### Linux

Open:

```text theme={null}
ENGINE_HOME/bin/startEngine.sh
```

Review its JVM memory settings, then run:

```bash theme={null}
cd "$ENGINE_HOME"
./bin/startEngine.sh
```

![Engine Deployment: Linux](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image-20201105-214934.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=2a9b135f4e91cbfd5a2afcb54d288665)

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.

![Engine Wizard](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/223165690-5336057a-8035-44f5-9892-1b9a77bb0cf8.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=b9eefaaea079bc7e356c6fbd91fc7610)

### 2 2. Configure the Germain Enterprise address

Enter the Germain Enterprise URL.

Example:

```text theme={null}
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.

![Engine Deployment: 3 3. Configure the proxy](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image-20211203-201309.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=56ceaee51904b1af7d354e7b542b29ee)

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

```text theme={null}
msiexec.exe /QN /I "C:\Install\GermainAPMEngines.msi" ^
  INSTALLFOLDER="C:\germain\engines" ^
  APM_SERVICEURL="https://germain.example.com"
```

With an HTTP proxy:

```text theme={null}
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"
```

| Argument | Required | Description |
| - | - | - |
| `/QN` | Yes | Runs the installer without a user interface |
| `/I "<msi-path>"` | Yes | Specifies the MSI package |
| `INSTALLFOLDER="<path>"` | No | Specifies the installation directory |
| `APM_SERVICEURL="<url>"` | Yes | Specifies the Germain Enterprise URL |
| `PROX="<type>"` | No | Specifies `http` or `https`; use lowercase |
| `APM_HTTPPROXY="<url:port>"` | No | Specifies the proxy URL and port |

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

```text theme={null}
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.

![Download link for GermainUX Engine](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/223165815-bbafe17a-aa05-493c-8e4b-9b4bd0c22dcb.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=b124ac05ab48f0aa03dda99a8f438b17)

That directory becomes `ENGINE_HOME`.

### 2. Configure JVM memory

Open:

```text theme={null}
ENGINE_HOME\bin\GermainEngineStandalone.xml
```

![Engine Deployment: 2. Configure JVM memory](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image2019-6-5_14-37-49.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=c3ff65c287336c96c712bbd55dd3e731)

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

Typical options include:

```html theme={null}
<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:

```text theme={null}
cd /d <ENGINE_HOME>\bin\WinSW
```

Run the script matching the installed .NET Framework:

```text theme={null}
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:

```text theme={null}
cd ..
GermainEngineStandalone.exe install
```

### 5. Verify the service

Open:

```text theme={null}
services.msc
```

![Engine Deployment: 5. Verify the service](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/engine-deployment/image2019-6-5_14-39-15.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=d0b21d49ede628a6d20ee9508470d4b1)

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:

```text theme={null}
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:

```text theme={null}
[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:

```text theme={null}
sudo cp "$ENGINE_HOME/bin/germain-engine.service" \
  /etc/systemd/system/germain-engine.service
```

Reload `systemd`:

```text theme={null}
sudo systemctl daemon-reload
```

Enable automatic startup:

```text theme={null}
sudo systemctl enable germain-engine.service
```

Start the service:

```text theme={null}
sudo systemctl start germain-engine.service
```

Check its status:

```text theme={null}
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:

```text theme={null}
/etc/init.d/germain-engine
```

The service can then be managed with:

```text theme={null}
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:

```text theme={null}
/opt/germain
```

### 2 2. Create the Docker network

```text theme={null}
docker network create germain
```

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

### 3 3. Start the required infrastructure

```text theme={null}
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:

```text theme={null}
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

```text theme={null}
cd /opt/germain
docker-compose -f compose/apm-services.yaml up -d --force-recreate
```

### 6. Configure the Engine

Open:

```text theme={null}
cd /opt/germain/config
nano engine.env
```

Configure the Germain Enterprise URL and other Engine settings.

### 7. Start the Engines

```text theme={null}
cd /opt/germain
docker-compose -f compose/apm-engines.yaml up -d --force-recreate
```

### 8. Validate the containers

```text theme={null}
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:

```text theme={null}
standalone
```

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

## Validate the deployment

After installation, confirm that:

* The Engine Manager process, service, or container is running.
* The correct Java version is active.
* The Engine Manager connects to the expected Germain Enterprise instance.
* The new node appears under **Germain > State**.
* The node is authorized.
* The Engine Manager heartbeat appears.

> [accordion] Show all 12
>
> * The expected Engine instances are listed.
> * Required Engines are enabled.
> * Monitoring components start successfully.
> * New telemetry appears in GermainUX.
> * CPU, memory, and disk usage remain within acceptable limits.
> * Automatic startup works after a controlled host restart.

Review:

```text theme={null}
ENGINE_HOME/logs/EngineManager.log
```

A successful startup includes:

```text theme={null}
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.

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> 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.

> [card] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.