Installation Enterperprise Glossary & Sync Service

This page includes a Step-by-Step installation Guide, a manual to configure the synchronization service and other helpful information about.

What's Inside the ZIP

The ContainerEG_<Version>.zip file contains everything needed to run the application in containers without internet access (air-gapped / offline).

File / Folder	Purpose
`enterpriseglossary-<version>.tar`	Pre-built Docker/Podman image for the web application
`enterpriseglossary-sync-<version>.tar`	Pre-built Docker/Podman image for the sync service (may be absent if not built)
`docker-compose.yml`	Compose definition for both services, volumes, and networking
`.env`	All configurable settings (ports, image tags, secrets)
`run.ps1`	Launch script for Docker (Windows or Linux with PowerShell)
`run-podman.ps1`	Launch script for Podman (Windows or Linux with PowerShell)
`stop.ps1`	Stops the Docker stack
`certs/`	Place your TLS certificate (`eg.pfx`) here before starting.
`README.md`	Quick-start reference

Step-by-Step Setup

Pick a Deployment Folder

Choose any folder where you want to install EG. Throughout this guide, this path is referred to as <deployment-folder>.

Extract the Build

After downloading the ContainerEG_<Version>.zip file and extract the folder into <deployment-folder>:

Windows PowerShell:

CODE

Expand-Archive -Path "<path-to>\DockerBuild.zip" `
               -DestinationPath "<deployment-folder>" `
               -Force
cd "<deployment-folder>"

Linux:

CODE

unzip DockerBuild.zip -d <deployment-folder>
cd <deployment-folder>

After extraction, the folder should contain:

CODE

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

Provide the TLS Certificate

EG runs over HTTPS and needs a .pfx file. For a first-time install

If your organization already provides a certificate use this one or create your certificate.
The filename must be eg.pfx.
Note the password — you'll need it in section 3.
Copy it to:

CODE

<deployment-folder>/certs/eg.pfx

Configure `.env`

Open <deployment-folder>/.env in any text editor and set CERT_PASSWORD to the password of your eg.pfx:

CODE

# Generated by TeamCity
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>

*See Configuration Reference bellow for details.

Start the Stack

Start the stack within your deployment folder using the Powershell script run.ps1.

Using the Powershell directly in Windows:

Using Docker:

CODE

.\run.ps1

Using Podman:

CODE

.\run-podman.ps1

From the Terminal (using Powershell):

Using Docker:

CODE

pwsh ./run.ps1

Using Podman:

CODE

pwsh ./run-podman.ps1

Both scripts accept 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		both containers will be created
EgWeb		only the web container
EGSync		only the sync container
EgWeb -EgSync		both containers, like when no parameter is used

Examples:

CODE

# Use a custom env file
.\run.ps1 -EnvPath ".\staging.env"
# Force-recreate containers
.\run.ps1 -ForceRecreate
# Podman with force-recreate
.\run-podman.ps1 -ForceRecreate

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

CODE

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

Verify

Once the script finishes, open a browser:

Protocol	URL
HTTP	`<http://localhost:8080`>
HTTPS	`<https://localhost:8443`>

Replace 8080 / 8443 with whatever you set in .env.

Stop the Stack (perform only when necessary)

Docker:

CODE

.\stop.ps1
# or manually:
docker compose down

Podman:

CODE

python -m podman_compose --project-name enterpriseglossary-project down

Configure Synchronization Service

The service must first be configured to connect to the desired Enterprise Glossary. In the following steps <container-name> refers to the name of the synchronization service container (e.g.enterpriseglossary-syncservice).

Download Config.xml

Log in to the Enterprise Glossary with an administrator user. In the settings menu in the upper right corner click Synchronization Jobs and then Download Config to download the configuration file for the synchronization service.

Adjust Config.xml

Open the downloaded Config.xml file in a text editor and replace localhost with web in the URL field:

CODE

<!-- Before -->
<Url>https://localhost:8443/</Url>

<!-- After -->
<Url>https://web:8443/</Url>

Find the container name

To find the exact name of the running synchronization service container, run one of the following commands:

Docker:

CODE

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

Podman:

CODE

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

Copy Config.xml into container directory

Copy the modified Config.xml file into the configuration directory of the running enterpriseglossary-syncservice container (use the container name you’ve determined in the last step) :

<container-name>:/app/config/

Example commands to copy the adjusted Config.xml into the directory:

Docker:

CODE

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

Podman:

CODE

podman cp /home/<username>/Config.xml <container-name>:/app/config/Config.xml

Restart Synchronization service

Finally, restart the synchronization service container for the changes to take effect:

Docker:

CODE

docker restart <container-name>

Podman:

CODE

podman restart <container-name>

Configuration Reference - `.env` Settings

Variable	Default	Description
`IMAGE_REGISTRY`	`localhost`	Image registry prefix. Do not change for offline deployments — the TAR images are tagged with `localhost/`.
`IMAGE_WEB_NAME`	`enterpriseglossary`	Name of the web image (must match the `.tar` filename prefix).
`IMAGE_SYNC_NAME`	`enterpriseglossary-sync`	Name of the sync service image (must match the `.tar` filename prefix).
`IMAGE_TAG`	(build version)	Image version tag (e.g., `1.2.3`). Must match the `.tar` filename suffix.
`PROJECT_NAME`	`enterpriseglossary-project`	Compose project name. Useful if running multiple instances side-by-side — give each a unique name.
`WEB_HTTP_PORT`	`8080`	Host port mapped to the web container's HTTP endpoint. Change if `8080` is already in use.
`WEB_HTTPS_PORT`	`8443`	Host port mapped to the web container's HTTPS endpoint. Change if `8443` is already in use.
`CONTAINER_HTTP_PORT`	`8080`	Port the app listens on inside the container. Do not change unless the application was built with a different port.
`CONTAINER_HTTPS_PORT`	`8443`	Same as above, for HTTPS. Do not change unless explicitly instructed.
`CERT_PASSWORD`	(set by build)	Password for the `eg.pfx` certificate file in `certs/`. Must match the actual PFX password.
`JWT_SECRET_KEY`	(set by build)	Secret key used for JWT token signing. Must be consistent across restarts to keep user sessions valid.

Services & Volumes

Web Service (`enterpriseglossary-web`)

Setting	Value
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 s (start grace: 60 s)
`extra_hosts`	`host.docker.internal → host-gateway` (allows the container to reach the host machine, e.g., for a database on localhost)

Volumes:

Volume	Mount Point	Purpose
`app-data`	`/app/App_Data`	Application data (database files, config) — persistent
`uploads`	`/app/wwwroot/uploads`	User-uploaded files — persistent
`./certs` (bind mount, read-only)	`/app/certs`	TLS certificate (`eg.pfx`)

Sync Service (`enterpriseglossary-syncservice`)

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

Volumes:

Volume	Mount Point	Purpose
`sync-config`	`/app/config`	Sync configuration (`Config.xml`) — persistent. Place or edit the sync config file here.
`sync-logs`	`/app/Logs`	Sync service log files — persistent

Environment variables set inside the sync container:

Variable	Value	Purpose
`DOTNET_ENVIRONMENT`	`Production`	.NET hosting environment
`DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT`	`true`	Enables HTTP/2 for gRPC / SignalR communication
`LD_LIBRARY_PATH`	`/app/runtimes/linux-x64/native`	Ensures native SAP libraries are found

Accessing Volume Data on the Host

Docker and Podman store named volumes in internal directories. To inspect or edit files:

CODE

# Docker — find the volume mount point
docker volume inspect enterpriseglossary-project_sync-config
# Copy Config.xml into the volume
docker cp ./Config.xml enterpriseglossary-syncservice:/app/config/Config.xml
# Or use a temporary container
docker run --rm -v enterpriseglossary-project_sync-config:/data -v $(pwd):/src alpine \
  cp /src/Config.xml /data/Config.xml

Common Scenarios

Change Ports

Edit .env:

CODE

WEB_HTTP_PORT=9090
WEB_HTTPS_PORT=9443

Then restart:

CODE

.\stop.ps1
.\run.ps1

Run Multiple Instances Side-by-Side

Extract the ZIP into a separate folder.

Edit .env — change PROJECT_NAME and ports to avoid conflicts:

CODE

PROJECT_NAME=eg-testing-instance2
WEB_HTTP_PORT=8081
WEB_HTTPS_PORT=8444

Run .\\run.ps1 from that folder.

Use a Different Certificate

Replace certs/eg.pfx with your new file (keep the filename eg.pfx).
Update CERT_PASSWORD in .env to match.
Restart the stack.

Connect to a Database on the Host Machine

To connect with a Database use the IP-Address of the Server where the Database is running on in your connection string.

The compose file maps host.docker.internal to the host gateway. So alternatively you can use host.docker.internal as the server address in the application's connection string (instead of localhost).

Troubleshooting

Symptom	Possible Cause	Fix
`run.ps1` fails with ".env not found"	Script not run from the deployment folder	`cd` into the extracted folder first
"Missing image TAR"	TAR file not next to the scripts	Ensure `*.tar` files are in the same directory as `run.ps1`
Port conflict ("address already in use")	Another process uses 8080/8443	Change `WEB_HTTP_PORT` / `WEB_HTTPS_PORT` in `.env`
HTTPS certificate error in browser	Self-signed or untrusted cert	Expected for test certs — click through the warning, or import the CA
Health check failing	App still starting or cert mismatch	Wait 60 s; verify `CERT_PASSWORD` matches `eg.pfx`
Podman: "podman_compose module not found"	`podman-compose` not installed	Run `python -m pip install podman-compose`
Sync service keeps restarting	`Config.xml` missing or invalid	Place a valid `Config.xml` in the `sync-config` volume (see volume section)

What's Inside the ZIP

Step-by-Step Setup

Pick a Deployment Folder

Extract the Build

Provide the TLS Certificate

Configure .env

Start the Stack

Verify

Stop the Stack (perform only when necessary)

Configure Synchronization Service

Configuration Reference - .env Settings

Services & Volumes

Web Service (enterpriseglossary-web)

Sync Service (enterpriseglossary-syncservice)

Accessing Volume Data on the Host

Common Scenarios

Change Ports

Run Multiple Instances Side-by-Side

Use a Different Certificate

Connect to a Database on the Host Machine

Troubleshooting

Configure `.env`

Configuration Reference - `.env` Settings

Web Service (`enterpriseglossary-web`)

Sync Service (`enterpriseglossary-syncservice`)