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

# GermainUX Enterprise (on Tomcat)

> GermainUX Enterprise can be deployed on Apache Tomcat within your organization’s data center, private cloud, or cloud account.

Service
`Enterprise`

Availability
2014.1

> [card] [Before You Begin](#before-you-begin)
>
> Compatibility checks first

> [card] [Configure Tomcat](#configure-tomcat)
>
> Tomcat settings for Germain

> [card] [Configure the Datastore](#configure-the-datastore)
>
> Connections and JDBC driver

> [card] [Configure Email](#configure-email)
>
> SMTP for alerts and reports

## Deploy GermainUX Enterprise on Apache Tomcat

### Overview

GermainUX Enterprise can be deployed on Apache Tomcat within your organization’s data center, private cloud, or cloud account.

This deployment includes the central services used to:

* Configure monitoring and automation
* Receive and process telemetry
* Query the GermainUX datastore
* Provide Workspace, dashboards, reports, and Session Replay
* Manage users, alerts, integrations, and system configuration

This guide covers a traditional Tomcat deployment. For container-orchestrated environments, use the Kubernetes or OpenShift deployment guides.

## Architecture

A typical GermainUX Enterprise deployment includes:

| Component | Purpose |
| - | - |
| **Apache Tomcat** | Hosts GermainUX Enterprise web applications and services |
| **Configuration database** | Stores GermainUX configuration |
| **Datamart or Elasticsearch** | Stores monitoring and analytical data |
| **Kafka** | Provides messaging between GermainUX components |
| **Hazelcast** | Supports internal distributed processing |
| **ZooKeeper** | Stores centralized GermainUX configuration where required |
| **GermainUX Services** | Provide configuration, ingestion, querying, analytics, and other platform capabilities |

ActiveMQ is not supported for current GermainUX releases beginning with 2024.2. It applies only to older deployments.

## Before You Begin

Confirm with Germain Software:

* GermainUX version
* Supported Java version
* Supported Tomcat version
* Supported datastore and driver
* Kafka, Hazelcast, and ZooKeeper requirements
* Required server distribution

> [accordion] Show all 11
>
> * License
> * Hardware sizing
> * Network ports
> * Authentication method
> * High-availability architecture

Do not independently upgrade Tomcat, Java, Kafka, Hazelcast, ZooKeeper, or the datastore without confirming compatibility.

### Requirements

Prepare:

* A supported 64-bit operating system
* Supported JDK
* Supported Apache Tomcat
* GermainUX Server distribution
* GermainUX license
* Prepared configuration database

> [accordion] Show all 14
>
> * Prepared datamart or Elasticsearch cluster
> * Kafka
> * Hazelcast and ZooKeeper when required
> * SMTP account
> * DNS name and TLS certificate
> * Service account
> * Required JDBC drivers
> * Network connectivity between all components

See:

* [Hardware](https://docs.germainux.com/main/hardware-requirements.md) Requirements
* [Network](https://docs.germainux.com/main/network-requirements.md) Requirements
* [Software](https://docs.germainux.com/main/software-requirements.md) Requirements
* [Storage](https://docs.germainux.com/main/storage-requirements.md) Requirements

## Recommended Installation Order

**1. Prepare the datastore**

**2. Install and configure ZooKeeper**

**3. Install and configure Kafka**

**4. Install Hazelcast when required**

**5. Install GermainUX Enterprise on Tomcat**

**6. Configure datastore connections**

**7. Configure messaging**

**8. Configure email and authentication**

**9. Initialize the GermainUX configuration**

**10. Start GermainUX services**

**11. Validate the complete deployment**

**12. Configure Sentinel for platform self-monitoring**

## Install GermainUX Enterprise

### 1 1. Extract the Distribution

Extract the GermainUX Server distribution into a temporary directory.

The distribution includes a Tomcat directory named according to the supported version, such as:

```text theme={null}
tomcat
tomcat9
```

Move this directory to the approved installation location.

Examples:

```text theme={null}
C:\GermainUX\Tomcat
/opt/germainux/tomcat
```

The final directory is referenced below as:

```text theme={null}
CATALINA_HOME
```

### 2. Set `CATALINA_HOME`

#### Windows

Set:

```text theme={null}
CATALINA_HOME=C:\GermainUX\Tomcat
```

#### Linux or Unix

Example:

```text theme={null}
export CATALINA_HOME=/opt/germainux/tomcat
```

Configure the environment variable for the service account that runs Tomcat.

### 3. Verify the Java Runtime

Confirm that Tomcat uses the supported JDK:

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

Set `JAVA_HOME` to the approved JDK installation.

Do not rely on an unrelated system Java installation.

## Configure Tomcat

### HTTP and HTTPS Ports

Tomcat commonly listens on port `8080` during initial setup.

The HTTP connector is configured in:

```text theme={null}
$CATALINA_HOME/conf/server.xml
```

Example:

```text theme={null}
<Connector
    port="8080"
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="8443" />
```

For production:

* Expose GermainUX through HTTPS.
* Use a reverse proxy or secured Tomcat connector.
* Restrict direct access to internal Tomcat ports.
* Do not expose the Tomcat shutdown or AJP ports unless required.
* Disable unused connectors.

The public URL should normally use port `443`.

### Memory

Configure JVM options in:

```text theme={null}
$CATALINA_HOME/bin/setenv.sh
```

or:

```text theme={null}
%CATALINA_HOME%\bin\setenv.bat
```

Example:

```bash theme={null}
export CATALINA_OPTS="$CATALINA_OPTS -Xms8g -Xmx8g -XX:+CrashOnOutOfMemoryError"
```

Memory settings must be based on the environment’s sizing assessment. Do not assume that 8 GB is sufficient for production.

Retain enough physical memory for the operating system and other services.

### Service Account and Permissions

Run Tomcat using a dedicated, non-personal service account.

The account requires access to:

* Tomcat installation
* Configuration
* Logs
* Temporary and working directories
* Java runtime
* Mounted certificates and truststores
* Required network destinations

Do not run Tomcat as `root` or a domain administrator.

## Install as a Windows Service

Open an elevated command prompt:

```text theme={null}
cd %CATALINA_HOME%
bin\service.bat install GermainAPMServer
```

This creates a Windows service with a name similar to:

```text theme={null}
Apache Tomcat <version> GermainAPMServer
```

Use the Tomcat service-management executable supplied with the installed Tomcat version to configure:

* Java Virtual Machine
* Initial and maximum memory
* JVM options
* Service account
* Startup mode
* Log locations

Add the following JVM option when approved:

```text theme={null}
-XX:+CrashOnOutOfMemoryError
```

This causes the JVM to terminate on an unrecoverable out-of-memory condition so the service manager or monitoring platform can restart it.

## Configure the Datastore

GermainUX normally uses separate connections for:

* Configuration data
* Datamart data
* Elasticsearch indexing and analytics, when Elasticsearch is used

Install the supported JDBC driver under the location specified by the GermainUX release.

### Configuration Database

Configure:

* Driver class
* JDBC URL
* Username
* Password
* TLS
* Connection pool
* Connection timeout

Applicable configuration keys include:

```text theme={null}
/config/germain/application/germain.config.driverClassName
/config/germain/application/germain.config.url
/config/germain/application/germain.config.username
/config/germain/application/germain.config.password
```

### Datamart

Applicable keys include:

```text theme={null}
/config/germain/application/germain.datamart.driverClassName
/config/germain/application/germain.datamart.url
/config/germain/application/germain.datamart.username
/config/germain/application/germain.datamart.password
```

Example structure:

```text theme={null}
set /config/germain/application/germain.datamart.driverClassName "<supported-driver>"
set /config/germain/application/germain.datamart.url "<secured-jdbc-url>"
set /config/germain/application/germain.datamart.username "<datamart-user>"
set /config/germain/application/germain.datamart.password "<secure-password>"
```

Do not use example accounts or disable TLS in production.

Store passwords through the secure credential mechanism supported by your GermainUX release rather than in scripts or source control.

### Elasticsearch

When Elasticsearch is used, configure:

```text theme={null}
/config/germain/application/germain.indexer.url
```

Example:

```text theme={null}
set /config/germain/application/germain.indexer.url "https://elasticsearch.example.com:9200"
```

Also configure the required authentication and certificate trust.

Do not use unsecured HTTP for production Elasticsearch connectivity.

## Configure Kafka

Kafka replaces ActiveMQ in GermainUX 2024.2 and later.

When Kafka runs on another host, configure its broker URL:

```text theme={null}
set /config/germain/application/germain.kafka.brokerUrl "<kafka-host>:9092"
```

Use the actual secured listener configured for your environment.

Production Kafka should include:

* Authentication
* TLS
* Restricted network access
* Replication
* Monitoring
* Appropriate retention
* High availability where required

See [Apache Kafka Setup](https://docs.germainux.com/main/apache-kafka-setup.md).

## Legacy ActiveMQ Configuration

ActiveMQ applies only to GermainUX releases earlier than 2024.2.

Legacy configuration key:

```text theme={null}
/config/germain/application/germain.messaging.brokerUrl
```

Do not configure ActiveMQ for a current GermainUX deployment unless Germain Software explicitly confirms that it is required.

## Configure Email

Configure SMTP for alerts, scheduled reports, notifications, and administrative email.

Applicable keys include:

```text theme={null}
/config/germain/application/spring.mail.from
/config/germain/application/spring.mail.host
/config/germain/application/spring.mail.username
/config/germain/application/spring.mail.password
/config/germain/application/spring.mail.port
/config/germain/application/spring.mail.properties.mail.smtp.auth
/config/germain/application/spring.mail.properties.mail.smtp.starttls.enable
```

Example structure:

```text theme={null}
set /config/germain/application/spring.mail.from "germain-alerts@example.com"
set /config/germain/application/spring.mail.host "smtp.example.com"
set /config/germain/application/spring.mail.username "<smtp-user>"
set /config/germain/application/spring.mail.password "<secure-password>"
set /config/germain/application/spring.mail.port "587"
set /config/germain/application/spring.mail.properties.mail.smtp.auth "true"
set /config/germain/application/spring.mail.properties.mail.smtp.starttls.enable "true"
```

Use your organization’s approved SMTP encryption and authentication settings.

## Configure Authentication

GermainUX supports:

| Method | Use |
| - | - |
| Database authentication | Default GermainUX-managed accounts |
| LDAP | Enterprise directory authentication |
| Microsoft Active Directory | Windows enterprise identity |
| OAuth | External identity-provider authentication |

Configure the selected method before production rollout and retain an approved recovery administrator account.

Test:

* Sign-in
* Sign-out
* User provisioning
* Role assignment
* Disabled-user handling
* Session expiration
* Identity-provider failure
* Administrative recovery

## Start and Stop Tomcat

### Linux or Unix

Start:

```bash theme={null}
cd $CATALINA_HOME
bin/startup.sh
```

Stop:

```bash theme={null}
cd $CATALINA_HOME
bin/shutdown.sh
```

For production, operate Tomcat through an approved service manager such as `systemd` rather than relying exclusively on interactive shell scripts.

### Windows Command Line

Start:

```text theme={null}
cd %CATALINA_HOME%
bin\startup.bat
```

Stop:

```text theme={null}
cd %CATALINA_HOME%
bin\shutdown.bat
```

### Windows Service

Use the Windows Services console or your approved service-management tooling to start and stop:

```text theme={null}
GermainAPMServer
```

![GermainUX Enterprise (on Tomcat): Windows Service](https://mintcdn.com/germain-ux/8KX3c-GSSWR99tdN/images/main/germain-ux-enterprise-on-tomcat/image-20201118-200502.png?fit=max\&auto=format\&n=8KX3c-GSSWR99tdN\&q=85\&s=687cb0ecb8f8084c371a49158c35de64)

## Validate the Deployment

Start infrastructure and GermainUX components in this order:

**1. Datastore**

**2. ZooKeeper**

**3. Kafka**

**4. Hazelcast**

**5. Tomcat and GermainUX core services**

**6. Remaining GermainUX services**

**7. GermainUX Engines and collectors**

Then confirm:

* Tomcat remains running.
* GermainUX Enterprise connects to the configuration database.
* GermainUX Enterprise connects to the datamart or Elasticsearch.
* Kafka connectivity succeeds.
* Hazelcast and ZooKeeper are healthy when used.
* GermainUX Workspace opens.

> [accordion] Show all 12
>
> * Administrator authentication works.
> * Configuration can be saved and retrieved.
> * Monitoring data is received.
> * Dashboards and analyses return data.
> * Email can be delivered.
> * No recurring startup errors appear in logs.

## Logs

Logs are located under:

```text theme={null}
$CATALINA_HOME/logs
```

Common files include:

| Log | Purpose |
| - | - |
| `catalina.out` | Primary Tomcat output on Linux or Unix |
| `catalina.<date>.log` | Tomcat lifecycle and container messages |
| `germainapmserver-stdout.<date>.log` | GermainUX Windows-service output |
| `config-services.log` | Configuration-service activity |
| `query-services.log` | Query-service activity |
| `ingestion-services.log` | Data-ingestion activity |

Review logs for:

* License errors
* Database connectivity failures
* Kafka connectivity failures
* TLS or certificate errors
* Authentication problems
* Port conflicts

> [accordion] Show all 9
>
> * Out-of-memory errors
> * Schema-version mismatches
> * Service startup failures

## Rollback Plan

Before changing or upgrading the deployment:

**1. Back up the GermainUX configuration database**

**2. Back up or snapshot the datamart**

**3. Back up Tomcat configuration**

**4. Back up ZooKeeper configuration**

**5. Record Kafka and datastore settings**

**6. Preserve the previous GermainUX distribution**

**7. Document the current service-start order**

**8. Test the rollback in a non-production environment**

If deployment validation fails:

**1. Stop Engines and collectors**

**2. Stop GermainUX services**

**3. Restore the previous Tomcat and GermainUX files**

**4. Restore the previous configuration**

**5. Restore databases only when required**

**6. Start the infrastructure**

**7. Start GermainUX services**

**8. Validate connectivity and data reception**

## Related Installation Guides

* [Apache Kafka Setup](https://docs.germainux.com/main/apache-kafka-setup.md)
* [Hazelcast Setup](https://docs.germainux.com/main/hazelcast-setup.md)
* ZooKeeper Setup
* GermainUX Services
* [GermainUX Initial Configuration](https://docs.germainux.com/main/germain-ux-init-configuration.md)
* Troubleshooting

For version-specific packages, configuration values, or deployment assistance, [contact Germain](https://docs.germainux.com/main/support.md) team.

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