Germain UX - Enterprise (on Tomcat)

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

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:

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:

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

⚙️ Requirements

Prepare:

See:

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

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:

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:

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:

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

🔧 Configuration Database

Configure:

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:

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:

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

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

📄 Logs

Logs are located under:

$CATALINA_HOME/logs

Common files include:

Review logs for:

• License errors

• Database connectivity failures

• Kafka connectivity failures

• TLS or certificate errors

• Authentication problems

• Port conflicts

• 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

• Hazelcast Setup

• ZooKeeper Setup

• GermainUX Services

• GermainUX Initial Configuration

• Troubleshooting

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