Run in Docker

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

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:

Download Scripts (setup.zip)

The setup.zip archive contains the following files:

Pull the Container Image

To pull the Enterprise GLossary images from the Theobald Software container registry:

1. Start Docker Desktop / Docker Engine.
2. Open a terminal, e.g., PowerShell on Windows.

3. Use the following command to log in to the Theobald Software container registry:

   docker login registry.theobald-software.com
   

4. When prompted, provide your credentials. Note that the password is not displayed in the terminal when typing.

5. Use the following commands to pull the Xtract Universal.iQ Enterprise Glossary images:

   docker pull registry.theobald-software.com/theobald-software/enterpriseglossary-sync:latest
   docker pull registry.theobald-software.com/theobald-software/enterpriseglossary:latest
   

   Pulling the images might take some time.

The Xtract Universal.iQ Enterprise Glossary images is now available in Docker.

Next, prepare a certificate for secure communication.

Provide a Certificate

It is recommended to set up Transport Layer Security (TLS) for the Enterprise Glossary container. To provide a certificate for TLS:

1. Create a dedicated folder on the machine that runs the Enterprise Glossary containers, e.g., C:\Docker\enterprise-glossary\.
2. Inside that folder, create a subfolder certs/ where you can store certificates.
3. Provide a Transport Layer Security (TLS) certificate to set up secure communication between clients and the Enterprise Glossary. The certificates requires 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 /certs/eg.pfx
4. Extract the content of the setup.zip archive into the root folder.
5. Open the .env file in a text editor of your choice and set CERT_PASSWORD to the password of your eg.pfx.

After creating the container, the Enterprise Glossary web UI is accessible via HTTPS protocol.

Next, create the container.

Create the Container

To create and run the Enterprise Glossary Docker stack, run the PowerShell script run.ps1 provided in the setup.zip archive. The script accepts the following optional parameters:

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

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

The synchronization server loads data into the Enterprise Glossary. To connect the synchronization service to Enterprise Glossary:

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

4. Use the following command to find the name of the running synchronization service container:

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

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

6. 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. 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.
2. Stop the running stack using the PowerShell script stop.ps1.
3. Load the new images using the PowerShell script run.ps1.

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

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

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: