Run in Docker

This page shows how to run Enterprise Glossary in Docker and how to configure the synchronization service.

The Xtract Universal.iQ Enterprise Glossary setup package contains everything needed to run Enterprise Glossary in a container. The package consists of the following files:

About the Enterprise Glossary Containers

Enterprise Glossary runs in two containers:

• The web service hosts the Enterprise Glossary application and user interface.
• The sync service executes synchronization jobs and imports metadata into Enterprise Glossary.

The graphic below shows which systems the Enterprise Glossary containers access and interact with.

For more information, see System Requirements.

Prerequisites

To run in a Docker environment, Enterprise Glossary requires:

• Docker Desktop
• Administrator rights
• Access to a Microsoft SQL Server

Load Container Images and Start the Containers

To run the Enterprise Glossary container stack:

1. Choose a folder where you want to install Enterprise Glossary. The folder is referred to as <deployment-folder> in the following steps.

2. Copy the content of the Xtract Universal.iQ Enterprise Glossary setup package into <deployment-folder>. The <deployment-folder> should contain the following files:

   <deployment-folder>/
   ├── enterpriseglossary-<version>.tar
   ├── enterpriseglossary-sync-<version>.tar
   ├── docker-compose.yml
   ├── .env
   ├── run.ps1
   ├── run-podman.ps1
   ├── stop.ps1
   ├── certs/
   └── README.md
   

   If the certs/ folder does not exist, create it.

3. Provide a Transport Layer Security (TLS) certificate with the following properties:

   • Use an organization provided certificate or create your certificate.
   • The certificate must be provided as a .pfx file. The filename must be eg.pfx.
   • Note the password of the .pfx file for later use.
   • Copy the file to <deployment-folder>/certs/eg.pfx

4. Open the .env file in a text editor of your choice and set CERT_PASSWORD to the password of your eg.pfx:

   .env File

   IMAGE_REGISTRY=localhost
   IMAGE_WEB_NAME=enterpriseglossary
   IMAGE_SYNC_NAME=enterpriseglossary-sync
   IMAGE_TAG=1.2.3
   PROJECT_NAME=enterpriseglossary-project
   # Ports exposed to the host
   WEB_HTTP_PORT=8080
   WEB_HTTPS_PORT=8443
   # Container ports (do not change unless the app listens on other ports)
   CONTAINER_HTTP_PORT=8080
   CONTAINER_HTTPS_PORT=8443
   # Secrets
   CERT_PASSWORD=ChangeMe123! # change to your password set in the .env
   JWT_SECRET_KEY=<keep the value generated by the build>
   

   For more information about the .env file settings, see Configuration Reference.

5. Run the PowerShell script .\run.ps1 to create and run the Docker stack. The script accepts the following optional parameters:

   Parameter	Default	Description
   -EnvPath	.env	Path to an alternative .env file.
   -ForceRecreate	(off)	Tears down and recreates containers even if already running.
   no parameter		Creates both containers.
   -EgWeb		Creates only the web container.
   -EGSync		Creates only the sync container
   -EgWeb -EgSync		Creates both containers, like when no parameter is used.

   Note

   You might have to load the images manually before running the stack:

   docker load -i .\enterpriseglossary-<version>.tar
   docker load -i .\enterpriseglossary-sync-<version>.tar
   

6. After the script finishes successfully, open a web browser and navigate to one of the following URLs. Replace 8080 and 8443 with the port numbers configured in the .env file:

   • HTTP: http://localhost:8080
   • HTTPS: https://localhost:8443

The Enterprise Glossary containers are up and running.

Next, configure the synchronization service container.

Configure the Synchronization Service

To connect the synchronization service to Enterprise Glossary:

1. Log in to Enterprise Glossary as an administrator and navigate to Settings > Synchronization Jobs > Download Config to download the Config.xml file.
2. Open the downloaded Config.xml file in a text editor of your choice and replace localhost with web in the URL field: <Url>https://localhost:8443/</Url> becomes <Url>https://web:8443/</Url>

3. Find the exact name of the running synchronization service container by running:

   docker ps --filter "name=sync" --format "{{.Names}}"
   

4. Copy the modified Config.xml file into the configuration directory of the running synchronization service container:

   docker cp /home/<username>/Config.xml <sync-service-container-name>:/app/config/Config.xml
   

5. Restart the synchronization service container for the changes to take effect:

   docker restart <sync-service-container-name>
   

The synchronization service now connects to Enterprise Glossary.

For information on common container scenarios, see Knowledge Base: Container Mainentance.

Common Errors

Update Enterprise Glossary

To update Xtract Universal.iQ Enterprise Glossary to a new version, load a new version of the image, adjust the .env file and start a new container from that image:

1. On your host machine, open the directory that contains your Enterprise Glossary images and the run.ps1 file.
2. Replace the enterpriseglossary-<version>.tar and the enterpriseglossary-sync-<version>.tar file with the new image files.
3. Open the .env file in a text editor and update the version number in the IMAGE_TAG entry. Alternatively, replace the .env file with the new .env file and change the certificate password in the new .env file.
4. Stop the running stack using the PowerShell script stop.ps1.
5. Load the new images using the PowerShell script run.ps1.

6. Open a web browser and navigate to one of the following URLs. Replace 8080 and 8443 with the port numbers configured in the .env file:

   • HTTP: http://localhost:8080
   • HTTPS: https://localhost:8443

The containers runs with the updated Enterprise Glossary version and your existing configuration.

Troubleshooting

Configuration Reference

The .env file contains the following settings:

Web Service Container

Configuration:

• Restart policy: unless-stopped.
• Memory limit: 14 GB.
• Memory reservation: 12 GB.
• Health check: curl -f -k https://localhost:<CONTAINER_HTTPS_PORT>/diagnostics/health every 30 seconds, with a 60-second startup grace period.
• extra_hosts: host.docker.internal:host-gateway (allows the container to access services running on the Docker host, e.g., a database on localhost)

Volumes:

Sync Service Container

Configuration:

• Restart policy: always.
• Memory limit: 5 GB.
• Memory reservation: 512 MB.
• Depends on: web (waits for a healthy status)
• Command: --configFile=/app/config/Config.xml

Volumes:

Environment variables: