Docker

The Orchestrator is available as a pre-built container image downloaded from the Maverics Console. You download the image as a .tar archive and load it into your local Docker image store with docker load. This approach works well for development, testing, and production environments where container orchestration is managed outside of Kubernetes.

Load the Container Image

The Console provides a pre-built container image as a .tar archive (maverics-orchestrator.tar). Download it from the Download Orchestrator Software modal inside any Deployment in the Console. Load the image into your local Docker image store:

docker load -i maverics-orchestrator.tar

After loading, the image is available as maverics-orchestrator. Confirm the image was loaded successfully:

docker images | grep maverics

Optionally, tag the image for organizational naming or version tracking:

docker tag maverics-orchestrator:latest my-registry.example.com/maverics-orchestrator:v2026.02.1

Run the Container

Start the Orchestrator container with port mappings for HTTP traffic and TLS, volume mounts for configuration and certificates, and any required environment variables:

docker run -d \
  --name maverics \
  -p 8080:8080 \
  -p 9443:9443 \
  -v /path/to/config:/etc/maverics \
  -v /path/to/certs:/etc/maverics/certs \
  -e MAVERICS_HTTP_ADDRESS=":8080" \
  maverics-orchestrator

-p 8080:8080 — HTTP traffic port
-p 9443:9443 — HTTPS/TLS traffic port (health endpoint default)
-v — Mounts for configuration and TLS certificates
-e — Environment variables for runtime configuration

Volume Mounts

The following volume mounts are recommended for production deployments:

Host Path	Container Path	Purpose
`/path/to/config`	`/etc/maverics`	Orchestrator YAML configuration files
`/path/to/certs`	`/etc/maverics/certs`	TLS certificates and private keys
`/path/to/logs`	`/var/log/maverics`	Log output directory (if file-based logging is configured)

Mount configuration and certificate directories as read-only where possible to follow the principle of least privilege:

-v /path/to/config:/etc/maverics:ro \
-v /path/to/certs:/etc/maverics/certs:ro

Environment Variables

Environment variables can be passed to the container individually with -e flags or in bulk using an environment file:

# Individual variables
docker run -e MAVERICS_HTTP_ADDRESS=":8080" -e MAVERICS_DEBUG_MODE="true" ...

# Environment file
docker run --env-file ./maverics.env ...

See Environment Variables for the complete list of supported variables.

Docker Compose Example

A docker-compose.yml for running the Orchestrator with persistent configuration and TLS:

services:
  maverics:
    image: maverics-orchestrator:latest
    container_name: maverics-orchestrator
    ports:
      - "8080:8080"
      - "9443:9443"
    volumes:
      - ./config:/etc/maverics:ro
      - ./certs:/etc/maverics/certs:ro
    environment:
      - MAVERICS_HTTP_ADDRESS=:8080
    restart: unless-stopped

Start the service:

docker compose up -d

Verify the Orchestrator is running:

curl -s https://localhost:9443/status
# Expected: {"status": "up"}

Stable Deployment Identity

The Orchestrator includes a soid field in every log entry for identifying and correlating logs by instance. By default, each container receives a unique soid because containers have ephemeral machine identities — this is the expected behavior for horizontally scaled deployments where each container is a distinct instance. For singleton deployment scenarios where you want the same soid to persist across container restarts (for example, a single Orchestrator container that gets recreated during updates), mount a stable /etc/machine-id file into the container:

docker run -d \
  --name maverics \
  -v /etc/machine-id:/etc/machine-id:ro \
  -v /path/to/config:/etc/maverics:ro \
  -p 8080:8080 \
  -p 9443:9443 \
  maverics-orchestrator

Or in Docker Compose:

services:
  maverics:
    image: maverics-orchestrator:latest
    volumes:
      - /etc/machine-id:/etc/machine-id:ro
      - ./config:/etc/maverics:ro
      - ./certs:/etc/maverics/certs:ro

See Logging — Deployment Correlation for more on how the soid field is used.

In-Place Config Reload

The Orchestrator applies configuration changes in place with zero downtime when it detects a config change. Three settings enable this in Docker:

1. Enable reload polling

Pass MAVERICS_RELOAD_CONFIG=true to the container:

docker run -e MAVERICS_RELOAD_CONFIG=true ...

2. Ensure a writable temp directory

The Orchestrator creates a Unix domain socket under $TMPDIR to coordinate the handoff. In standard Docker containers /tmp is writable, so no additional configuration is needed. If you run the container with --read-only, mount a writable tmpfs and point TMPDIR to it:

docker run --read-only \
  --tmpfs /run/maverics:rw,noexec,nosuid \
  -e TMPDIR=/run/maverics \
  -e MAVERICS_RELOAD_CONFIG=true \
  ...

3. Mount a stable machine identity

The Orchestrator uses /etc/machine-id to derive the handoff socket path. If it computes a different path across the reload (which happens when the file is missing and it falls back to a random UUID), the reload applies the new config but in-flight state (sessions, caches) is lost. Mount the host’s /etc/machine-id into the container. This is the same mount shown in Stable Deployment Identity — it serves both log correlation and state-preserving reloads:

docker run -v /etc/machine-id:/etc/machine-id:ro ...

Docker Compose example

A complete docker-compose.yml with all three settings:

services:
  maverics:
    image: maverics-orchestrator:latest
    container_name: maverics-orchestrator
    ports:
      - "8080:8080"
      - "9443:9443"
    volumes:
      - ./config:/etc/maverics:ro
      - ./certs:/etc/maverics/certs:ro
      - /etc/machine-id:/etc/machine-id:ro
    environment:
      - MAVERICS_HTTP_ADDRESS=:8080
      - MAVERICS_RELOAD_CONFIG=true
    restart: unless-stopped

If your config file is mounted read-only from a host directory and you update it in place, the Orchestrator detects the change within the polling interval (default 30s) and performs the reload automatically — no docker restart required.

See the troubleshoot guide for diagnostic commands if reloads are not taking effect.

Installation Overview

System requirements, download options, CLI flags, and environment variables

Configuration

Configure the Orchestrator after installation

Getting Started

End-to-end quick-start guide

Console Administration

Orchestration

Load the Container Image

Run the Container

Volume Mounts

Environment Variables

Docker Compose Example

Stable Deployment Identity

In-Place Config Reload

1. Enable reload polling

2. Ensure a writable temp directory

3. Mount a stable machine identity

Docker Compose example

Installation Overview

Configuration

Getting Started

​Load the Container Image

​Run the Container

​Volume Mounts

​Environment Variables

​Docker Compose Example

​Stable Deployment Identity

​In-Place Config Reload

​1. Enable reload polling

​2. Ensure a writable temp directory

​3. Mount a stable machine identity

​Docker Compose example

​Related Pages

Installation Overview

Configuration

Getting Started

Load the Container Image

Run the Container

Volume Mounts

Environment Variables

Docker Compose Example

Stable Deployment Identity

In-Place Config Reload

1. Enable reload polling

2. Ensure a writable temp directory

3. Mount a stable machine identity

Docker Compose example

Related Pages