> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
docker load -i maverics-orchestrator.tar
```

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

```bash theme={null}
docker images | grep maverics
```

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
-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:

```bash theme={null}
# 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](/reference/orchestrator/installation#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:

```yaml theme={null}
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:

```bash theme={null}
docker compose up -d
```

Verify the Orchestrator is running:

```bash theme={null}
curl -s https://localhost:9443/status
# Expected: {"status": "up"}
```

## Stable Deployment Identity

The Orchestrator includes a [`soid`](/introduction/glossary#soid-secure-orchestrator-id) 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:

```bash theme={null}
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:

```yaml theme={null}
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](/reference/orchestrator/telemetry/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:

```bash theme={null}
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:

```bash theme={null}
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](#stable-deployment-identity) — it serves
both log correlation and state-preserving reloads:

```bash theme={null}
docker run -v /etc/machine-id:/etc/machine-id:ro ...
```

### Docker Compose example

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

```yaml theme={null}
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
```

> [!NOTE]
>
> 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](/guides/operations/troubleshoot#configuration-issues) for diagnostic commands if reloads are not taking effect.

## Related Pages

> **[Installation Overview](/reference/orchestrator/installation)**
>
> System requirements, download options, CLI flags, and environment variables

> **[Configuration](/reference/orchestrator/configuration)**
>
> Configure the Orchestrator after installation

> **[Getting Started](/introduction/getting-started)**
>
> End-to-end quick-start guide