GermainUX Enterprise (on Tomcat)

ServiceEnterprise

Availability2014.1

Before You Begin

Compatibility checks first

Configure Tomcat

Tomcat settings for Germain

Configure the Datastore

Connections and JDBC driver

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

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

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 Requirements
Network Requirements
Software Requirements
Storage Requirements

Recommended Installation Order

Prepare the datastore

Install and configure ZooKeeper

Install and configure Kafka

Install Hazelcast when required

Install GermainUX Enterprise on Tomcat

Configure datastore connections

Configure messaging

Configure email and authentication

Initialize the GermainUX configuration

Start GermainUX services

Validate the complete deployment

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:

tomcat
tomcat9

Move this directory to the approved installation location. Examples:

C:\GermainUX\Tomcat
/opt/germainux/tomcat

The final directory is referenced below as:

CATALINA_HOME

2. Set `CATALINA_HOME`

Windows

Set:

CATALINA_HOME=C:\GermainUX\Tomcat

Linux or Unix

Example:

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:

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:

$CATALINA_HOME/conf/server.xml

Example:

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

$CATALINA_HOME/bin/setenv.sh

or:

%CATALINA_HOME%\bin\setenv.bat

Example:

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:

cd %CATALINA_HOME%
bin\service.bat install GermainAPMServer

This creates a Windows service with a name similar to:

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:

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

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

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

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:

/config/germain/application/germain.indexer.url

Example:

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:

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.

Legacy ActiveMQ Configuration

ActiveMQ applies only to GermainUX releases earlier than 2024.2. Legacy configuration key:

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

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

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:

cd $CATALINA_HOME
bin/startup.sh

Stop:

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:

cd %CATALINA_HOME%
bin\startup.bat

Stop:

cd %CATALINA_HOME%
bin\shutdown.bat

Windows Service

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

GermainAPMServer

GermainUX Enterprise (on Tomcat): Windows Service

Validate the Deployment

Start infrastructure and GermainUX components in this order:

Datastore

ZooKeeper

Kafka

Hazelcast

Tomcat and GermainUX core services

Remaining GermainUX services

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.

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:

$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

Show all 9

Out-of-memory errors
Schema-version mismatches
Service startup failures

Rollback Plan

Before changing or upgrading the deployment:

Back up the GermainUX configuration database

Back up or snapshot the datamart

Back up Tomcat configuration

Back up ZooKeeper configuration

Record Kafka and datastore settings

Preserve the previous GermainUX distribution

Document the current service-start order

Test the rollback in a non-production environment

If deployment validation fails:

Stop Engines and collectors

Stop GermainUX services

Restore the previous Tomcat and GermainUX files

Restore the previous configuration

Restore databases only when required

Start the infrastructure

Start GermainUX services

Validate connectivity and data reception

Apache Kafka Setup
Hazelcast Setup
ZooKeeper Setup
GermainUX Services
GermainUX Initial Configuration
Troubleshooting

For version-specific packages, configuration values, or deployment assistance, contact Germain team.

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.

Before You Begin

Configure Tomcat

Configure the Datastore

Configure Email

​Deploy GermainUX Enterprise on Apache Tomcat

​Overview

​Architecture

​Before You Begin

​Requirements

​Recommended Installation Order

​Install GermainUX Enterprise

​1 1. Extract the Distribution

​2. Set CATALINA_HOME

​Windows

​Linux or Unix

​3. Verify the Java Runtime

​Configure Tomcat

​HTTP and HTTPS Ports

​Memory

​Service Account and Permissions

​Install as a Windows Service

​Configure the Datastore

​Configuration Database

​Datamart

​Elasticsearch

​Configure Kafka

​Legacy ActiveMQ Configuration

​Configure Email

​Configure Authentication

​Start and Stop Tomcat

​Linux or Unix

​Windows Command Line

​Windows Service

​Validate the Deployment

​Logs

​Rollback Plan

​Related Installation Guides

​Get Help

Contact GermainUX Support

Can't find what you need?

Deploy GermainUX Enterprise on Apache Tomcat

Overview

Architecture

Before You Begin

Requirements

Recommended Installation Order

Install GermainUX Enterprise

1 1. Extract the Distribution

2. Set `CATALINA_HOME`

Windows

Linux or Unix

3. Verify the Java Runtime

Configure Tomcat

HTTP and HTTPS Ports

Memory

Service Account and Permissions

Install as a Windows Service

Configure the Datastore

Configuration Database

Datamart

Elasticsearch

Configure Kafka

Legacy ActiveMQ Configuration

Configure Email

Configure Authentication

Start and Stop Tomcat

Linux or Unix

Windows Command Line

Windows Service

Validate the Deployment

Logs

Rollback Plan

Related Installation Guides

Get Help