Deploy Management with Docker

Running the Management image with Docker on an operator workstation or an operator-created Linux VM is a supported deployment option. It runs the same Management web application as the Management ISO. You manage the host operating system, container runtime, networking, time synchronization, TLS and persistent storage yourself.

The commands below start a fresh instance. They do not install the Appliance nodes or change an existing Management instance.

Runtime Versions

Use these minimum versions for this guide. Install a maintained patch release that meets or exceeds them.

Component Minimum version Requirement

Component	Minimum version	Requirement
Docker Engine and CLI	28.0	Run Linux containers. Enable the containerd image store when exporting release or update bundles for Management.
Docker Desktop on Windows or macOS	4.39.0	Use its Linux engine. This Desktop release includes Docker Engine 28 and supports the archive-export commands.
Docker Compose plugin	2.17.0	Required for the Compose option, which uses `docker compose up --wait --wait-timeout`.

Docker Engine and CLI

28.0

Run Linux containers. Enable the containerd image store when exporting release or update bundles for Management.

Docker Desktop on Windows or macOS

4.39.0

Use its Linux engine. This Desktop release includes Docker Engine 28 and supports the archive-export commands.

Docker Compose plugin

2.17.0

Required for the Compose option, which uses docker compose up --wait --wait-timeout.

Check Docker’s client and server versions with docker version and the Compose plugin with docker compose version.

Docker’s platform-specific image export requires Engine API 1.48 or later. See the Docker Desktop 4.39 release notes and Compose 2.17 release notes for the corresponding tool capabilities.

Prepare the Host

Reserve the Management CPU, memory and persistent storage allocations, in addition to the host’s own needs. On Docker Desktop, allocate these resources to its Linux engine.
Use a rootful Linux Docker Engine, including Docker Desktop on Windows and macOS. Use a Management image built for the engine’s native AMD64 or ARM64 architecture. Rootless runtimes are outside these examples.
Check that the container can reach the Appliance nodes, DNS, NTP and any required registries. Keep the workstation and its container engine awake during installation, updates, backups and recovery.
Choose a Management DNS name and a host IP address reachable by its operators. Reserve host ports 80 and 443, or choose another HTTPS port before first start.

Management runs its services and Operations scripts in one container with a read-only root filesystem. Keep /var persistent and mount temporary filesystems at /run and /tmp. Use a trusted workstation or dedicated VM whose administrators may access Management credentials. Do not mount the container engine socket or the host root filesystem into Management.

Start with Docker Compose

Docker Compose starts Management from a configuration file. Use this instead of the direct Docker commands below. The files use MTG’s Management Compose configuration. Set the image tag supplied for your selected release and supply the initial administrator password through the shell.

Download compose.yaml and template.env into a new directory for this Management instance, or copy the following blocks into files with those names.

compose.yaml

name: mtg-ers-vapp

services:
  management:
    image: repo.mtg.de/releases/ers/vapp/management:${MTG_MANAGEMENT_VERSION:?Set the Management tag supplied for the selected release}
    hostname: management
    pull_policy: ${MTG_MANAGEMENT_PULL_POLICY}
    read_only: true
    tmpfs:
      - /run:size=512m,mode=0755
      - /tmp:size=512m,mode=1777
    mem_limit: 8g
    pids_limit: 2048
    stop_grace_period: 90s
    restart: unless-stopped
    environment:
      - APPLIANCE_HOSTNAME=${MTG_MANAGEMENT_HOSTNAME}
      - APPLIANCE_HTTPS_PORT=${MTG_MANAGEMENT_HTTPS_PORT}
      - APPLIANCE_ACME_DIRECTORY_URL=${MTG_MANAGEMENT_ACME_DIRECTORY_URL:-}
      - APPLIANCE_ACME_EMAIL=${MTG_MANAGEMENT_ACME_EMAIL:-}
      - INITIAL_GITEA_ADMIN_PASSWORD
    ports:
      - "${MTG_MANAGEMENT_BIND_ADDRESS}:${MTG_MANAGEMENT_HTTP_PORT}:30080/tcp"
      - "${MTG_MANAGEMENT_BIND_ADDRESS}:${MTG_MANAGEMENT_HTTPS_PORT}:30443/tcp"
    volumes:
      - management-data:/var
      - type: bind
        source: ${MTG_MANAGEMENT_TLS_DIRECTORY:-./tls}
        target: /run/management-appliance/tls
        read_only: true

volumes:
  management-data:

template.env

# Review the tag and network values before the first start.
MTG_MANAGEMENT_VERSION=REPLACE_WITH_MTG_MANAGEMENT_TAG
# Use never after loading the image on a disconnected Docker host.
MTG_MANAGEMENT_PULL_POLICY=missing
MTG_MANAGEMENT_BIND_ADDRESS=127.0.0.1
MTG_MANAGEMENT_HTTP_PORT=80
MTG_MANAGEMENT_HTTPS_PORT=443
MTG_MANAGEMENT_HOSTNAME=management-appliance.localhost
MTG_MANAGEMENT_TLS_DIRECTORY=./tls
# Leave empty when supplying tls/tls.crt and tls/tls.key.
MTG_MANAGEMENT_ACME_DIRECTORY_URL=
MTG_MANAGEMENT_ACME_EMAIL=
# Supply INITIAL_GITEA_ADMIN_PASSWORD from the shell, not this file.

Install the Docker Compose plugin and prepare the Management image on the destination host. For an air-gapped host, load the transferred image before starting Compose. In the directory containing the two files, prepare the configuration:

cp template.env .env
chmod 600 .env
mkdir -p tls

Review .env before starting. For an air-gapped host, set MTG_MANAGEMENT_PULL_POLICY=never and use the loaded image’s tag. Set MTG_MANAGEMENT_VERSION to the qualified Management tag supplied with the selected release bundle. The default address and hostname allow browser access on the same workstation. For an operator-created VM, set MTG_MANAGEMENT_BIND_ADDRESS to the VM’s reachable IP and MTG_MANAGEMENT_HOSTNAME to its DNS name. To change the hostname later, follow the hostname-change procedure.

Place the hostname certificate and key in tls/tls.crt and tls/tls.key. Allow container UID/GID 65532 to read the pair and traverse the directory. On Linux, a dedicated TLS directory can use group 65532, mode 0750 for the directory and 0640 for the files. Protect the key from other host users.

Alternatively, set the ACME directory URL and email in .env and leave tls/ empty. ACME HTTP-01 requires the CA to reach the Management hostname on port 80. A complete supplied pair takes precedence over ACME. Verify the certificate after startup; internal health does not prove certificate issuance.

In Bash, read the initial password, validate the configuration without printing its contents and start Management:

read -r -s -p 'Initial Management administrator password: ' INITIAL_GITEA_ADMIN_PASSWORD
printf '\n'
export INITIAL_GITEA_ADMIN_PASSWORD
# The password must contain at least 12 characters.
docker compose --env-file .env --file compose.yaml config --quiet
docker compose --env-file .env --file compose.yaml up --detach --wait --wait-timeout 900
unset INITIAL_GITEA_ADMIN_PASSWORD

The named volume is mtg-ers-vapp_management-data by default. Docker Compose’s project name prefixes it, so it is separate from the direct docker run example’s management-data volume. Preserve the Docker Compose project name, volume and TLS directory when resuming the same instance.

Do not add --volumes to docker compose down; that would delete Management data.

Open the configured Management HTTPS URL and sign in as mtg-admin. Continue with connected or air-gapped Appliance preparation, then install the Appliance.

The initial password is needed only to initialize the volume. It does not reset an existing administrator password. These commands inspect, stop and resume this deployment:

docker compose --env-file .env --file compose.yaml ps
docker compose --env-file .env --file compose.yaml logs --tail 100 --follow management
# Stop after active operations finish; retain the data volume.
docker compose --env-file .env --file compose.yaml stop --timeout 120
# Resume using the same files, project and volume.
docker compose --env-file .env --file compose.yaml up --detach --wait --wait-timeout 900

Compose sets restart: unless-stopped. Management resumes when the Docker engine restarts unless you stopped it explicitly. Keep the host available during operations and manage Docker startup with the host operating system.

Select the Image and Settings for a Direct Launch

Follow Prepare the Management container image to pull the image on a connected host or transfer and load it on an air-gapped host. Use the exact Management build supplied with the selected release bundle. Management checks its version and build ID before installation, update or recovery.

Run the following in Bash. Replace each example value.

MANAGEMENT_TAG='REPLACE_WITH_MTG_MANAGEMENT_TAG'
MANAGEMENT_IMAGE="repo.mtg.de/releases/ers/vapp/management:${MANAGEMENT_TAG}"
MANAGEMENT_DNS='management.example.com'
MANAGEMENT_BIND_IP='192.0.2.10'
MANAGEMENT_HTTPS_PORT='443'
TLS_DIRECTORY="$PWD/management-tls"

MANAGEMENT_BIND_IP must be an address assigned to the container host. Configure MANAGEMENT_DNS to resolve to it. For access only from the workstation running Docker, use 127.0.0.1 and a hostname resolving to that address. Remote operators need a routable address and matching firewall rules. For a later hostname change, follow the hostname-change procedure.

Prepare TLS and the Administrator Password

Create management-tls on the container host. Place a PEM certificate chain for MANAGEMENT_DNS in tls.crt and its matching unencrypted private key in tls.key. Keep this directory access-controlled and allow container UID/GID 65532, used by Traefik, to traverse it and read both files. For a private CA, establish trust on operator workstations before sign-in.

The examples mount this directory read-only. The ISO console’s certificate staging workflow does not apply to a container on your own host. Without a supplied pair or ACME configuration, Management generates a temporary self-signed certificate for its hostname. Do not use that fallback as the deployment’s persistent TLS identity.

Read the initial administrator password without putting its value in shell history. Use at least 12 characters. Keep shell tracing disabled:

read -r -s -p 'Initial Management administrator password: ' INITIAL_GITEA_ADMIN_PASSWORD
printf '\n'
export INITIAL_GITEA_ADMIN_PASSWORD

The runtime receives the password through the environment. Container-host administrators can inspect that environment and the persisted bootstrap data. Protect both the host and the data volume.

Start the Container

Run this after pulling the selected image and preparing the settings above:

docker volume create management-data
docker run -d \
  --name management-appliance \
  --hostname management-appliance \
  --read-only \
  --tmpfs /run:size=512m,mode=0755 \
  --tmpfs /tmp:size=512m,mode=1777 \
  --memory 8g \
  --pids-limit 2048 \
  --stop-timeout 90 \
  --pull=never \
  -e "APPLIANCE_HOSTNAME=$MANAGEMENT_DNS" \
  -e "APPLIANCE_HTTPS_PORT=$MANAGEMENT_HTTPS_PORT" \
  -e INITIAL_GITEA_ADMIN_PASSWORD \
  -p "$MANAGEMENT_BIND_IP:80:30080" \
  -p "$MANAGEMENT_BIND_IP:$MANAGEMENT_HTTPS_PORT:30443" \
  --mount "type=bind,source=$TLS_DIRECTORY,target=/run/management-appliance/tls,readonly" \
  -v management-data:/var \
  "$MANAGEMENT_IMAGE"
unset INITIAL_GITEA_ADMIN_PASSWORD

docker logs --tail 100 --follow management-appliance

Exit the log view with Ctrl+C; the container continues running. Check readiness with the image’s health probe:

docker exec management-appliance /opt/management-appliance/scripts/healthcheck.sh

First startup can take several minutes while Management initializes its services. Wait for the health probe to succeed. Open management.example.com/, using your chosen hostname and adding the HTTPS port if it is not 443. Verify the expected certificate and sign in as mtg-admin with the initial password.

A healthy internal probe does not prove that DNS, the host firewall or the browser’s certificate trust is correct. Check those separately if the page is unreachable.

Continue with connected or air-gapped Appliance preparation, then install the Appliance. Docker registry login does not configure registry credentials inside Management.

Stop, resume and retain State

Complete active operations and retain the generated artifact bundle outside Management before stopping it. Stop and resume Management with:

docker stop --time 120 management-appliance
docker start management-appliance

The direct Docker launch commands require an explicit start after a host reboot. For an always-on operator VM, configure startup and graceful shutdown through your host’s service manager after verifying the deployment.

The named volume mounted at /var retains Management’s application state, repositories, registry credentials, images and logs. Keep it across container recreation. Do not share one volume between two running instances. The TLS directory is retained separately. Saving the Management image to a tar file does not preserve the data volume or TLS directory.

A restart ends Management’s in-memory Appliance access. Reconnect with the retained artifact bundle when needed. The Appliance continues running when Management stops. Consult Security and hardening for host access, network restrictions and storage protection.

Change the hostname

Finish active operations and retain required downloads.
Point the new DNS name at the Docker host. If you supply a certificate, replace it with a pair covering the new name.

For Compose, change MTG_MANAGEMENT_HOSTNAME in .env, then recreate the service:

docker compose --env-file .env --file compose.yaml up --detach --force-recreate --wait --wait-timeout 900

For a direct launch, stop and remove the container, then repeat the launch with the new MANAGEMENT_DNS and the same management-data volume and TLS directory.
Open the new HTTPS URL, sign in again and reconnect the Appliance.

Retain the same Compose project and persistent volume. Startup updates the login callback while keeping the Git user, repositories and automation identity. The Management ISO keeps its hostname and HTTPS port fixed after initialization.

Replace the Management image

Use the image supplied for the selected release bundle.

Finish active operations and retain the artifact bundle and required downloads outside Management.
Pull or load the qualified image.
For Compose, set MTG_MANAGEMENT_VERSION in .env. For a loaded offline image, set MTG_MANAGEMENT_PULL_POLICY=never. Recreate the service, retaining the same project, volume and TLS directory:
```
docker compose --env-file .env --file compose.yaml up --detach --force-recreate --wait --wait-timeout 900
```
For a direct launch, stop and remove the container, then repeat the launch with the selected image and the same volume and TLS directory.
Sign in again and restore cluster access before continuing with the selected bundle.