Docker Containers

Starting from version 3.4.0, UDMG is available as a custom Docker image.

Image Variants

The image is offered in two variants that differ only in the base operating system layer. The UDMG Server binary is the same in both.

• RHEL: built on redhat/ubi10-minimal. Use this variant if your organization requires Red Hat base images.
• Debian: built on debian:trixie. A suitable default for most deployments without a specific OS policy requirement.

If your organization has no base image policy, either variant works.

Downloading a UDMG Docker Image

To obtain the Docker image, contact your Stonebranch representative. If you do not have a representative, reach out to support@stonebranch.com.

Architecture

UDMG Server runs inside a Docker container as a non-privileged user. It connects outward to a database, which must be running and reachable before the container starts.

External Partners reach UDMG Server through port mappings configured at container start time for each Local Server Endpoint.

Admins access the UDMG Admin UI and UDMG REST API through the same mechanism on port 8080.

The work directory is bind-mounted from the host so that state persists across container restarts and removals.

Prerequisites

Database

UDMG Server requires a running database. For setup instructions, refer to Database Installation.

Work Directory

UDMG Server uses the Work Directory Path as the base directory for relative paths in the Configuration File.

By default, when the work directory path is not set as an environment variable or in the Configuration File, the work directory resolves to the process's current working directory. In a container, that is /app (the container's working directory), which lives inside Docker's ephemeral writable layer and is discarded when the container is removed.

To preserve the work directory across container restarts and removals, bind mount a host directory as the Work Directory Path.

Complete the following steps to set up the bind mount:

1. Create the directory on the host:
   $

   sudo mkdir -p <host-work-directory>

2. Set ownership to the container user (UID 10010, GID 0):
   $

   sudo chown 10010:0 <host-work-directory>

3. When running the container, pass the host directory with -v and set the container-side path to match, using either an environment variable or the Configuration File:
   Environment Variables

   $

   docker run -d \
    --name udmg \
    -p 8080:8080 \
    -v <host-work-directory>:<work-directory-path> \
    -e UDMG_WORK_DIRECTORY_PATH=<work-directory-path> \
    -e UDMG_JWT_SIGNING_KEY=<signing-key> \
    -e UDMG_DATABASE_ENGINE=<engine> \
    -e UDMG_DATABASE_HOSTNAME=<hostname> \
    -e UDMG_DATABASE_PORT=<port> \
    -e UDMG_DATABASE_NAME=<database-name> \
    -e UDMG_DATABASE_USER=<database-user> \
    -e UDMG_DATABASE_PASSWORD=<database-password> \
    -e UDMG_SECURITY_PASSPHRASE_KEY=<passphrase-key> \
    <image-name>:<tag>

   Configuration File

   $

   docker run -d \
    --name udmg \
    -p 8080:8080 \
    -v <host-work-directory>:<work-directory-path> \
    -v <path-to-existing-config-file>:/config/udmg-server.hcl:ro \
    <image-name>:<tag>

   udmg-server.hcl

   work_directory_path = "<work-directory-path>"

Port Mapping

Docker does not expose container ports to the host automatically. This applies even when running locally: a service bound to a port inside the container is unreachable from the host until that port is mapped.

This includes both the ports used by UDMG Server itself and the ports required by any UDMG as Server pipeline.

To make a port accessible, map it explicitly using -p <host-port>:<container-port> when running the container:

$

docker run -d \
--name udmg \
-p 8080:8080 \
<image-name>:<tag>

Local FTPS Server Endpoints require a passive port range in addition to the main port. Each data connection uses a port from this range, so the entire range must be mapped. Use a single flag to map a range:

$

docker run -d \
--name udmg \
-p 21100-21200:21100-21200 \
<image-name>:<tag>

Port mappings are set at container start time and cannot be changed on a running container. To avoid unplanned restarts, map all ports you expect to need upfront.

If you do not know all required ports upfront, a common workflow is to:

1. Start the container with the ports you know.
2. Configure your Endpoints.
3. Stop and re-run the container with all original settings (your environment variables or Configuration File mount) plus the additional -p those new Endpoints require. Because state is stored in the work directory and database (not inside the container), this does not cause data loss.

For the full list of ports declared by the image, refer to Default Port Numbers.

Running a UDMG Container

There are two ways to provide configuration when running a UDMG container:

• Environment Variables (Recommended): pass required parameters as -e flags on docker run, overriding the default Configuration File bundled in the image.
• Custom Configuration File: mount a complete HCL Configuration File from the host into the container, replacing the default Configuration File bundled in the image.

Environment Variables (Recommended)

Pass configuration parameters directly to docker run using -e flags.

The following command includes the minimum required parameters to start UDMG:

$

docker run -d \
--name udmg \
-p 8080:8080 \
-v <host-work-directory>:<work-directory-path> \
-e UDMG_WORK_DIRECTORY_PATH=<work-directory-path> \
-e UDMG_JWT_SIGNING_KEY=<signing-key> \
-e UDMG_DATABASE_ENGINE=<engine> \
-e UDMG_DATABASE_HOSTNAME=<hostname> \
-e UDMG_DATABASE_PORT=<port> \
-e UDMG_DATABASE_NAME=<database-name> \
-e UDMG_DATABASE_USER=<database-user> \
-e UDMG_DATABASE_PASSWORD=<database-password> \
-e UDMG_SECURITY_PASSPHRASE_KEY=<passphrase-key> \
<image-name>:<tag>

warning

Do not use localhost as the database hostname. Inside a container, localhost refers to the container itself, not the host machine or any external service. Use the hostname or IP address of the server where the database runs.

warning

If the database already contains data from a previous UDMG installation, set passphrase_key to the same value used in that installation. Generating a new key causes a startup failure: the server cannot decrypt existing encrypted data.

For guidance on generating these values, see Configuration. For valid database engine values, see database.engine. For a full list of options, see Environment Variables.

Once the container is running, the Admin UI is accessible at http://localhost:8080/ui/signin (replace localhost and 8080 with your host address and the port you mapped).

Custom Configuration File

Mount a Configuration File from the host into the container at /config/udmg-server.hcl by following these steps:

1. Extract the Default Configuration File

The image bundles a complete, documented Configuration File. Extract it to the current directory as a starting point:

$

docker run --rm \
--entrypoint cat \
<image-name>:<tag> \
/config/udmg-server.hcl > udmg-server.hcl

2. Edit the Configuration File

The extracted file contains all required configuration blocks with default values. Open it and set the following values — the rest of the file can be left as-is:

work_directory_path = "<work-directory-path>"

jwt {
  signing_key = "<signing-key>"
}

database {
  engine   = "<engine>"
  hostname = "<hostname>"
  port     = <port>
  name     = "<database-name>"
  user     = "<database-user>"
  password = "<database-password>"
}

security {
  passphrase_key = "<passphrase-key>"
}

warning

Do not use localhost as the database hostname. Inside a container, localhost refers to the container itself, not the host machine or any external service. Use the hostname or IP address of the server where the database runs.

warning

If the database already contains data from a previous UDMG installation, set passphrase_key to the same value used in that installation. Generating a new key causes a startup failure: the server cannot decrypt existing encrypted data.

For guidance on generating these values, see Configuration. For valid database engine values, see database.engine. For a full list of options, see Configuration File.

3. Validate the Configuration File

To validate the Configuration File before starting the container, run the test command in a throwaway container:

$

docker run --rm \
--entrypoint /app/udmg-server \
-v <path-to-existing-config-file>:/config/udmg-server.hcl:ro \
<image-name>:<tag> \
test --file /config/udmg-server.hcl

If the Configuration File is valid, the command exits without output. If there are errors, they are printed to the terminal. For example, a missing required block produces output such as:

Configuration file contains errors:

File: /config/udmg-server.hcl
Line: 1 Column: 1
Summary: Missing jwt block
Detail: A jwt block is required.

Line:

---

The output may also include source context lines (marked with ->) indicating where in the file the error was detected.

4. Run the Container

Once the Configuration File is validated, mount it into the container:

$

docker run -d \
--name udmg \
-p 8080:8080 \
-v <host-work-directory>:<work-directory-path> \
-v <path-to-existing-config-file>:/config/udmg-server.hcl:ro \
<image-name>:<tag>

Default Port Numbers

The following table lists the UDMG Server default port numbers:

Default Port Number	Description	Configuration File Argument	Environment Variable
8080	UDMG Server API Port	api.port	UDMG_API_LISTEN_PORT
7070	UDMG Server Observability API Port	observability.api.port	UDMG_OBSERVABILITY_API_LISTEN_PORT
4222	UDMG Server Cluster Client Port	cluster.client_port	UDMG_CLUSTER_CLIENT_PORT
6222	UDMG Server Cluster Server Port	cluster.cluster_port	UDMG_CLUSTER_CLUSTER_PORT
8443	The UDMG Web Transfer Client (WTC) port. Disabled by default; set wtc.enable = true to enable.	wtc.port	UDMG_WTC_LISTEN_PORT
9090	UDMG Hook Server port (for AS2 Asynchronous MDN traffic). Disabled by default; set hook_server.enable = true to enable.	hook_server.port	UDMG_HOOK_SERVER_PORT

CLI Commands

The udmg-server binary at /app/udmg-server provides CLI commands for administrative operations such as enrolling a license, resetting a user password, or rotating encryption keys. Use docker exec against a running container:

$

docker exec <container-name> /app/udmg-server <command> --config /config/udmg-server.hcl

Commands that require database access need --config /config/udmg-server.hcl. Commands that prompt interactively (such as for a password) also need the -it flags. For a full list of available commands and options, see UDMG Server CLI.

Testing the Configuration File

To validate a Configuration File on the host without starting a container, run the test command in a throwaway container:

$

docker run --rm \
--entrypoint /app/udmg-server \
-v <path-to-existing-config-file>:/config/udmg-server.hcl:ro \
<image-name>:<tag> \
test --file /config/udmg-server.hcl

Enrolling a License

To enroll a license using license enroll, choose between two methods: Interactive, which accepts the key pasted directly into the terminal, or License File, which accepts a path to a file copied into the container.

Interactive

Run the following command with the -it flags against a running container:

$

docker exec -it <container-name> /app/udmg-server license enroll --config /config/udmg-server.hcl

The command waits for input without displaying a prompt. Paste the license key, press Enter, then press Ctrl+D to signal end of input. The command confirms enrollment on success.

License File

Complete the following steps against a running container:

1. Copy a temporary license file into the container:
   $

   docker cp <license-file> <container-name>:/tmp/license.key

2. Apply the license:
   $

   docker exec <container-name> /app/udmg-server license enroll --license /tmp/license.key --config /config/udmg-server.hcl

3. Remove the temporary license file:
   $

   docker exec <container-name> rm /tmp/license.key

Entrypoint

The UDMG Docker image has a simple entrypoint that adds support for the OpenShift arbitrary UIDs and then proceeds to start UDMG using the binary (/app/udmg-server) and the Configuration File at /config/udmg-server.hcl. This is either the default Configuration File with values overridden by environment variables, or a custom file mounted at that path, as explained in Running a UDMG Container.

Image Labels

UDMG images include labels that provide metadata about the image, such as the version, base image, and build information.

OCI Labels

These labels follow the OCI Image Format Specification.

Label	Description	Example Value
org.opencontainers.image.authors	The contact details of the organization that created the image.	support@stonebranch.com
org.opencontainers.image.base.name	The name of the base image the UDMG Server image was created with.	docker.io/redhat/ubi10-minimal:latest
org.opencontainers.image.base.digest	The digest of the base image the UDMG Server image was created with.	sha256:26dc3089ab244…
org.opencontainers.image.created	An ISO8601 timestamp of when the image was created.	2026-01-15T16:00:00Z
org.opencontainers.image.description	A description of the UDMG Server image and what it is used for.	UDMG Server
org.opencontainers.image.ref.name	The name of the component in the image.	udmg
org.opencontainers.image.title	The title for the image.	UDMG installed in a Red Hat base image
org.opencontainers.image.vendor	The organization distributing the image.	Stonebranch, Inc.
org.opencontainers.image.version	The version of the application inside the image.	3.4.0

RHEL Labels

These labels follow the Red Hat OpenShift Software Certification Policy Guide.

Label	Description	Example Value
name	The image name.	udmg-server
vendor	The company name.	Stonebranch, Inc.
version	The image version.	3.4.0
release	The image release.	3.4.0
summary	A short description of the image.	Universal Data Management Gateway Server
description	A description of the image.	UDMG Server provides managed file transfer capabilities including REST API, Web Transfer Client, and protocol engines.