Globalyzer Server Docker Installation

From Lingoport Wiki
Jump to navigation Jump to search


Globalyzer Server Docker Based Installation

The following instructions cover the installation of a Globalyzer Server instance on an internally controlled virtual machine running a Docker instance in which the Globalyzer Server is installed.

In the event that a forward proxy is leveraged within the network for all external traffic, note the inclusion of "REQUIRED FOR FORWARD PROXY ONLY" indicated sections for specific instructions for handling that part of the configuration.


Deployment Architecture

  • Two containers on a single VM:
    • Globalyzer Server: Tomcat 9 running the Globalyzer Server WAR application
    • MySQL 8.0: Database with persistent storage (named container: "gzserverDatabase")

Containers communicate via Docker network "mysqlnetsgzserver". Both containers auto-restart unless explicitly stopped.


System Requirements

VM Specifications

  • CPU: 2+ cores recommended
  • RAM: 4GB minimum (Java heap: 256m initial, 1600m max)
  • Disk: 100GB or more depending upon DB size
  • OS: Linux with Docker support

Ports

  • 8080: HTTP access to Globalyzer Server (configurable)
  • 3306: MySQL (container-internal only, not exposed)


REQUIRED FOR FORWARD PROXY ONLY

Proxy outbound connections pass through ports

  • 3128: http outbound
  • 3128` https outbound

This configuration assumes that all outbound http/https connections made on the VM will be routed through a forward proxy similar to Squid.


Prerequisites

  • Docker installed and running
  • Git LFS installed - Used for syncing the installation files from GitHub if that method is selected below.
    • Available in RHEL9 using DNF
  • Sudo privileges on the Deployment VM
  • Docker Hub credentials for "lingoportcustomer" organization
  • SMTP credentials (username, password) for email notifications

REQUIRED FOR FORWARD PROXY ONLY

  • Forward proxy installed and functional
    • Confirm using curl command similar to:
 curl -x http://<PROXY_URL>:<PROXY_PORT>  https://www.google.com

Installation of Docker

In order to run dnf as noted below, the dnf configuration file must be set to use the proxy for all outbound communications. To do so edit the "/etc/dnf/dnf.conf" configuration file and add the proxy details there. If authentication is required to access the proxy, this would also be performed here. Below is an example with the proxy added to the last line of the configuration. 

 [main]
 gpgcheck=1
 installonly_limit=3
 clean_requirements_on_remove=True
 best=False
 skip_if_unavailable=True
 proxy=http://proxy.mycorp.local:8080  # REQUIRED FOR FORWARD PROXY ONLY

If Docker Engine is not already installed on the host, use the Docker CE repository for RHEL. 

 # Optional: remove older Docker-related packages first
 sudo dnf remove \
   docker \
   docker-client \
   docker-client-latest \
   docker-common \
   docker-latest \
   docker-latest-logrotate \
   docker-logrotate \
   docker-engine \
   podman \
   runc
   
 # Add the Docker CE repository
 sudo dnf -y install dnf-plugins-core
 sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
   
 # Install Docker Engine and common plugins
 sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   
 # Start Docker now and on boot
 sudo systemctl enable --now docker

REQUIRED FOR FORWARD PROXY ONLY

At this point, we need to allow Docker itself to communicate through the proxy. Since dockerd runs a a systemd service, it will not inherit shell proxy variables, so we need to add this to the service itself. 

 # Create this directory if it does not already exist
 sudo mkdir -p /etc/systemd/system/docker.service.d
 
 # Create a /etc/systemd/system/docker.service.d/http-proxy.conf file
 # in the directory with these contents customized for the installation instance
 # Adjust these values to match your organizations requirements.
 [Service]
 Environment="HTTP_PROXY=http://proxy.example.com:8080"
 Environment="HTTPS_PROXY=http://proxy.example.com:8080"
 Environment="NO_PROXY=localhost,127.0.0.1,.example.local"

The docker service needs to be aware of these changes and restarted 

 sudo systemctl daemon-reload
 sudo systemctl restart docker

Validate the configuration was read into docker 

 systemctl show --property=Environment docker
 # There should be something like this presented:
 Environment=HTTP_PROXY=...


Confirm Docker installations are possible using hello-world 

 # Verify Docker works
 sudo docker run hello-world

REQUIRED FOR FORWARD PROXY ONLY

Edit the file /root/.docker/config.json file and add the below. This will inject proxy related variables into the container for applications that will support them. 

   {
       "auths": {
           "https://index.docker.io/v1/": {
           "auth": "***********************"
           }
       },
       "proxies": {
           "default": {
               "httpProxy": "http://proxy.example.com:3128",
               "httpsProxy": "http://proxy.example.com.io:3128",
               "noProxy": "localhost,127.0.0.1"
           }
       }
   }

To validate the effect of this addition, run the following command with the running container ID. There will now be both upper and lower case formats of the proxy information shown in the environment. 

 [root@ip-172-31-51-200 ~]# sudo docker exec 8d7b2dffc1ae env
 PATH=/usr/local/tomcat/bin:/opt/java/openjdk/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 HOSTNAME=8d7b2dffc1ae
 https_proxy=http://proxy.example.com:3128
 NO_PROXY=localhost,127.0.0.1
 no_proxy=localhost,127.0.0.1
 HTTP_PROXY=http://proxy.example.com:3128
 http_proxy=http://proxy.example.com:3128
 HTTPS_PROXY=http://proxy.example.com:3128
 JAVA_HOME=/opt/java/openjdk
 LANG=en_US.UTF-8
 LANGUAGE=en_US:en
 LC_ALL=en_US.UTF-8
 JAVA_VERSION=jdk-11.0.29+7
 CATALINA_HOME=/usr/local/tomcat
 TOMCAT_NATIVE_LIBDIR=/usr/local/tomcat/native-jni-lib
 LD_LIBRARY_PATH=/usr/local/tomcat/native-jni-lib
 TOMCAT_MAJOR=9
 TOMCAT_VERSION=9.0.113
 TOMCAT_SHA512=************************************************
 COMMAND_CENTER_CONFIG=/usr/local/tomcat/CommandCenterConfig.groovy
 HOME=/usr/local/tomcat

Zip and Git LFS Installation

 sudo dnf -y install zip
 sudo dnf -y install git
 sudo dnf -y install git-lfs
 sudo git lfs install


Globalyzer Server Installation Files

REQUIRED FOR FORWARD PROXY ONLY

Git does not respect the forward proxy settings at the container level so this must be performed to tell it to leverage the proxy. Note this must be done for the user that will be running the git command. It only impacts that user. 

 git config --global http.proxy http://proxy.company.com:8080

For both forward proxy and non forward proxy. At the time of this writing, only the second option is currently available. Please contact support@lingoport.com if there is a desire to install Globalyzer Server within a local network so that we can supply you with the required files.

There are two options. First is to Clone the repo to obtain the Globalyzer Server files like this:

  • Clone repository
 git clone <repository-url>
 cd globalyzer-server-docker
  • Second option is to unzip the globalyzer zip file in the home directory of the user that the Docker files exist in.
 unzip globalyzer-server-docker-client-20260708_150715.zip
   
 cd globalyzer-server-docker-client-20260708_150715
  
 # Verify LFS files downloaded (artifacts should be large binaries, not pointer files)
 ls -lh gzserver-enterprise.war server-subcomponents/
  
 # Configure installation
 Edit `install.conf` before installation:
 vim install.conf

The install.conf Configuration

Here is the install.conf example. Update it as appropriate. Use password generator for passwords to ensure randomness. 

 # Installation location.  This is an example.  Generally can be the
 # home directory of the user with sudo rights.
 home_directory=/home/centos
   
 # Docker image tag suffix / version
 gzserver_image_version=gzserver-6.8
   
 # Server settings
 serverPort=8080
 gzserver_url=gzserver.example.com # Public hostname only; do not include http://, https://, port, or /gzserver
 
 # MySQL
 database_root_password=<strong-password> # Create using a password generator if possible
   
 # Application database user
 database_app_user=lingoport
 # (another unique password similar to one used for root)
 database_app_password=<app-password>
   
 # SMTP (for email notifications) This assumes you are using mailgun
 # for an SMTP server.  If not there will be an additional edit
 # required post configuration.
 email_username=<smtp-username>
 email_password=<smtp-password>
   
 # Docker Hub (for pulling lingoport/gzserver image)
 docker_username=lingoportcustomer
 docker_account_token=<your-token>
   
 # Image repository
 docker_image=lingoport/gzserver_customer


Installation Execution

 # Run installation
 sudo ./InstallGzserver.sh

Installation takes ~8 minutes.

Additional Notes regarding some fields in the install.conf file

  • docker_image contract:
  • docker_image may be either a repository name or a fully tagged image reference.
    • The recommended default is the repository only: lingoport/gzserver_customer.
    • If docker_image already includes a tag, the install and update scripts will use it as-is.
    • If docker_image does not include a tag, the scripts append :<gzserver_image_version>.
  • gzserver_image_version contract:
    • gzserver_image_version is the exact Docker tag suffix used with docker_image when docker_image is untagged.
    • For the current customer registry tags, use values such as gzserver-6.8.
    • This means the default image reference resolves to lingoport/gzserver_customer:gzserver-6.8.
  • gzserver_url contract:
    • Set gzserver_url to the public DNS hostname only, for example gzserver.example.com.
    • Do not include http:// or https://`.
    • Do not include a port such as :8080.
    • Do not include the application path /gzserver.
    • The app expands this into https://<gzserver_url>/gzserver for generated absolute links.
  • Host/network expectation:
    • Before a reverse proxy is set up, the app is reachable locally on the VM over plain HTTP at http://localhost:<serverPort>/gzserver.
    • For normal user access, put a reverse proxy or load balancer in front of the app, terminate TLS there, and forward traffic to serverPort on the VM.
    • Point public DNS for gzserver_url at that reverse proxy or host.

Once the installation is finished and the server is running, run the final FinishInstallAfterStartupFinished.sh script. 

 sudo ./FinishInstallAfterStartupFinished.sh
  • What it does:
    • Main Script
    1. Creates directories: $home_directory/lingoport/, $home_directory/gzserver/config/, $home_directory/gzserver/backup/, $home_directory/gzserver/mysql/conf.d/
    2. Creates Docker network: mysqlnetsgzserver
    3. Starts MySQL container (gzserverDatabase) with UTF-8 configuration
    4. Waits for MySQL to be ready (up to 60 seconds with health checks)
    5. Starts Globalyzer Server container
    6. Injects your config values into GzserverConfig.groovy
    7. Restarts Globalyzer Server to apply configuration
    8. Final database tweaks (Finish Install Script)

Important MySQL persistence note

The host directory $home_directory/gzserver/mysql/data is persistent. If it already contains MySQL data from a previous install attempt, MySQL will keep using the original root password from when that directory was first initialized. Changing database_root_password in install.conf does not reset an already-initialized MySQL data directory.

Container IDs saved to:

  • $home_directory/gzserver/config/gz_container_id.txt - Globalyzer Server
  • $home_directory/gzserver/config/gz_mysql_id.txt - MySQL

Copy Globalyzer License Into Container

Obtain the container ID for the container that is currently running Globalyzer Server. Run the below command and copy the ID of the container running Globalyzer Server, it will be used in the next step. 

    sudo docker ps

Take the license supplied by Lingoport and place it on the VM in your users home directory. Next we copy this license in to the /tmp directory in the container as a temporary storage location 

    sudo docker cp <PATH_TO_LICENSE_ON_VM> <CONTAINER_ID>:/tmp/

Create command line alias for login to container

The below allows you to type gotogzroot at the terminal and you will land in the container as root user. 

 # Edit the .bashrc in the VM and add this at the bottom of the file
 alias gotogzroot="sudo docker exec -it -u root `sudo docker ps | grep lingoport/gzserver | awk '{print $1}' ` bash"
 # Save the file and source it to load it in
 source ~/.bashrc

Log into the container

Log into the container using the new alias create 

    gotogzroot

Update SMTP Server in Container if Needed

 # When not using mailgun as an SMTP server, log into the container as root and edit the entry for host or SMTP mail will not connect
 # /usr/local/tomcat/GzserverConfig.groovy
   
 host = "smtp.mailgun.com"  << == Update this!!
 port = 465
 username = "user@example.com"
 password = "********"

Install New License In Application within Container

Make a backup of the Globalyzer.license if one already exists and copy over the new license to the proper location 

    cd /usr/local/tomcat
    cp Globalyzer.license Globalyzer.license_bak
    cp /tmp/Globalyzer.license ./Globalyzer.license

Verification

After installation completes: 

 # Restart the Globalyzer Server Container so the license takes effect
 sudo docker container <CONTAINER_ID> stop
 sudo docker container <CONTAINER_ID> start
   
 # Should see both containers with status "Up"
 # lingoport/gzserver_customer:gzserver-6.8 on port 8080
 # mysql:8.0 with name "gzserverDatabase"
  
 # Check Globalyzer Server logs
 CONTAINER_ID=$(cat $home_directory/gzserver/config/gz_container_id.txt)
 sudo docker logs $CONTAINER_ID | tail -20
   
 # Look for: "Server startup in [X] milliseconds"

Access the application

http://<vm-ip>:<serverPort>/gzserver

(Replace <serverPort> with value from "install.conf", default is 8080)

Quick host-side curl test before reverse proxy/TLS setup: 

   curl -i http://localhost:<serverPort>/gzserver/login
   
   # Or just return the HTTP status code
   curl -s -o /dev/null -w '%{http_code}\n' http://localhost:<serverPort>/gzserver/login

Use plain HTTP for this local test. Do not use "https://" until TLS termination is configured in front of the app.

Login

For a fresh install, the bundled default local administrator credentials are: 

   Username: admin@lingoport.com
   Password: <reach out to support@lingoport.com for password>

Change this password immediately after first login.

If you are connecting to an existing deployment, use that deployments current Globalyzer administrator credentials instead.

Common Operations

Backup Database

Using the backup script:

   sudo ./BackupGzserverDatabase.sh

This creates a timestamped backup file in `$home_directory/gzserver/backup/GZSERVER_backup_YYYYMMDD_HHMM.sql`.

Restore Database

Using the restore script:

   sudo ./RestoreGzserverDatabase.sh YYYYMMDD_HHM

   Example: sudo ./RestoreGzserverDatabase.sh 20251010_1430

The script will:

  • Locate the backup file for the specified date
  • Restore the database
  • Update the container ID file if needed

View Logs

   CONTAINER_ID=$(cat $home_directory/gzserver/config/gz_container_id.txt)
   sudo docker logs -f $CONTAINER_ID

Restart Server

   CONTAINER_ID=$(cat $home_directory/gzserver/config/gz_container_id.txt)
   sudo docker restart $CONTAINER_ID

Access Database

   # Using container name
   sudo docker exec -it gzserverDatabase mysql -u root -p
   
   # Or using container ID
   MYSQL_ID=$(cat $home_directory/gzserver/config/gz_mysql_id.txt)
   sudo docker exec -it $MYSQL_ID mysql -u root -p

Upgrading Globalyzer Server

Automated Update Using the update script:

   # Edit install.conf to specify new version
   vim install.conf  # Update gzserver_image_version
   
   # Run the update script
   sudo ./UpdateGzserver.sh

The update script performs:

  1. Validates configuration (prompts for missing values)
  2. Stops the current Globalyzer Server container (but does not remove it)
  3. Creates automatic database backup to $home_directory/gzserver/backup/
  4. Pulls new Docker image from Docker Hub
  5. Starts new container with updated version
  6. Applies configuration from install.conf
  7. Restarts container to apply changes

Note: The MySQL container and data remain untouched during updates. Only the Globalyzer Server container is replaced.

Update the Globalyzer License

Since the Globalyer.license resides in the container, it will need to be updated following the same procedure that was used during an installation. Obtain the container ID for the container that is currently running Globalyzer Server. Run the below command and copy the ID of the container running Globalyzer Server, it will be used in the next step. 

    sudo docker ps

Take the license supplied by Lingoport and place it on the VM in your users home directory. Next we copy this license in to the /tmp directory in the container as a temporary storage location 

    sudo docker cp <PATH_TO_LICENSE_ON_VM> <CONTAINER_ID>:/tmp/

Install New License In Application within Container

Make a backup of the Globalyzer.license if one already exists and copy over the new license to the proper location 

    cd /usr/local/tomcat
    cp Globalyzer.license Globalyzer.license_bak
    cp /tmp/Globalyzer.license ./Globalyzer.license

Rollback Procedure

Note that roll backs, especially to a previous version, will entail some risk. In general leveraging backups at the VM itself will provide a more reliable method.

To rollback to a previous version

  • Edit install.conf to specify previous version
 vim install.conf  # Change gzserver_image_version to previous version
  • Run the update script (it works for rollback too)
 sudo ./UpdateGzserver.sh
  • If needed, restore database backup
 sudo ./RestoreGzserverDatabase.sh YYYYMMDD_HHMM


Uninstalling

Using the uninstall script:

 sudo ./UninstallGzserver.sh
  • What it does:
    1. Stops and removes the Globalyzer Server container
    2. Stops and removes the MySQL container
    3. Leaves backup files and configuration in place

Note: This does NOT remove:

  • Docker images
  • Docker network
  • Backup files in $home_directory/gzserver/backup/
  • Configuration files in $home_directory/gzserver/config/

To completely remove everything

   # After running UninstallGzserver.sh
   sudo docker network rm mysqlnetsgzserver
   sudo docker rmi lingoport/gzserver:<version>
   sudo docker rmi mysql:8.0
   rm -rf $home_directory/gzserver
   rm -rf $home_directory/lingoport

Configuration Reference

Manual Configuration Changes

To change configuration after installation: 

 CONTAINER_ID=$(cat $home_directory/gzserver/config/gz_container_id.txt)
   
 # Edit config inside container
 sudo docker exec -it $CONTAINER_ID vim /usr/local/tomcat/GzserverConfig.groovy
   
 # Restart to apply
 sudo docker restart $CONTAINER_ID

Troubleshooting

Installation Issues

Container won't start

  • Check Docker daemon
 sudo systemctl status docker
  • Check port availability
 sudo netstat -tlnp | grep 8080
  • View container logs for errors
  sudo docker logs $(cat $home_directory/gzserver/config/gz_container_id.txt)

Database connection errors:

  • Verify MySQL is running
 sudo docker ps | grep gzserverDatabase
  • Or use container ID
 MYSQL_ID=$(cat $home_directory/gzserver/config/gz_mysql_id.txt)
 sudo docker exec $MYSQL_ID mysql -u root -p<password> -e "SHOW DATABASES;"
  • Check network connectivity between containers
 sudo docker network inspect mysqlnetsgzserver

MySQL not ready during installation:

The install script waits up to 60 seconds for MySQL to be ready. If installation fails with MySQL readiness errors:

  1. Check MySQL container logs: `sudo docker logs gzserverDatabase`
  2. Verify MySQL image pulled correctly: `sudo docker images | grep mysql`
  3. Check available disk space: `df -h`

MySQL root password rejected during installation:

If the installer says MySQL did not accept the configured root credentials, the usual cause is an existing data directory at $home_directory/gzserver/mysql/data.

  1. Option: keep the existing database
    • Update install.conf with the original MySQL root password used when the data directory was first created
  sudo ./InstallGzserver.sh
  1. Option: start fresh
  sudo rm -rf $home_directory/gzserver/mysql/data/*
  sudo ./InstallGzserver.sh

The installer removes the temporary gzserverDatabase container after this failure, but it does not delete the persisted MySQL data directory.

Git LFS Issues

  • WAR file is a pointer file (130 bytes instead of ~50MB):
 git lfs pull
 git lfs checkout
  • Cloned without Git LFS:
    • Install Git LFS
   sudo dnf install git-lfs 
   git lfs install
   # Pull LFS files
   git lfs pull

Runtime Issues

Out of memory errors:

  • Edit server-config/hosted.sh and increase heap size:
 export JAVA_OPTS="-Xms512m -Xmx2048m -Dstringchararrayaccessor.disabled=true"
  • Rebuild image and redeploy using `UpdateGzserver.sh`.

Slow performance:

  • Check VM resources: top, free -h, df -h
  • Check Java heap usage in logs
  • Consider increasing VM RAM or Java heap size

MySQL authentication plugin errors:

  • The installation uses `mysql_native_password`. If you see authentication errors, verify the MySQL container started with --default-authentication-plugin=mysql_native_password.

Script Issues

  • Update script fails:
    • Check if containers are running
sudo docker ps
  • Verify config file has all required values
cat install.conf
  • Check Docker Hub credentials
 echo $docker_account_token | docker login -u $docker_username --password-stdin
  • Restore script can't find backup:
    • List available backups
 ls -lh $home_directory/gzserver/backup/
 Restore expects format: GZSERVER_backup_YYYYMMDD_HHMM.sql

Command Center fails to communicate with Globalyzer Server

If the Command Center instance which pulls rule sets from the Globalyzer instance sits behind a forward proxy, the below can be added to the Command Center Instance to allow communications to pass through the forward proxy. The below assumes the that step has already been taken where the /root/.docker/config.json file has been updated to use the forward proxy.

REQUIRED FOR FORWARD PROXY ONLY

In the event that this instance needs to have connectivity to the the outside world from within the web applications UI and the system sits behind a proxy, the following file must be created. This is created inside of the container at ~/bin/setenv.sh 

 #!/bin/sh
   
 # The below will pull the values out of the environment 
 git config --system http.proxy "$HTTP_PROXY"
 git config --system https.proxy "$HTTPS_PROXY"
   
 exec catalina.sh run
  
 CATALINA_OPTS="$CATALINA_OPTS \
 -Dhttp.proxyHost=proxy.example.com \
 -Dhttp.proxyPort=3128 \
 -Dhttps.proxyHost=proxy.example.com \
 -Dhttps.proxyPort=3128 \
 -Dhttp.nonProxyHosts=localhost,127.0.0.1"
   
 export CATALINA_OPTS

Once created the docker application must be restarted in order for this to take effect.

Backup Best Practices

Automated backups:

If possible at the VM level perform regular backups to retain the entire VM contents.

If needed there are methods to back up the DB itself in addition. Create a cron job to run backups regularly: 

 # Edit crontab
 crontab -e
  
 # Add daily backup at 2 AM
 0 2 * * * cd /path/to/globalyzer-server-docker && sudo ./BackupGzserverDatabase.sh
   
 # Add weekly cleanup (keep last 30 days)
 0 3 * * 0 find $HOME/gzserver/backup/ -name "GZSERVER_backup_*.sql" -mtime +30 -delete

Backup retention:

Backups include full timestamps (YYYYMMDD_HHMM), allowing multiple backups per day. Consider:

  • Daily backups retained for 30 days
  • Weekly backups retained for 3 months
  • Monthly backups retained for 1 year

Testing restores:

Regularly test your restore procedure to ensure backups are valid: 

 # Test restore on a dev/test system
 sudo ./RestoreGzserverDatabase.sh YYYYMMDD_HHMM

Verify data integrity through the web interface

Copyright (c) Lingoport 2025-2026

Retrieved from "https://wiki.lingoport.com/index.php?title=Globalyzer_Server_Docker_Installation&oldid=100287"