---
title: "Docker - Pilot Docs"
description: "Run Pilot as a Docker container"
url: "https://docs.calinora.io/deployment/docker/"
---

# Docker

Pilot is distributed as a minimal Docker image (~20MB, distroless) with multi-architecture support for `amd64` and `arm64`.

## Image

```bash
docker pull calinora/pilot:latest
```

Pin to a specific version:

```bash
docker pull calinora/pilot:0.27.0
```

## Basic Usage

```bash
docker run -d \
  --name pilot \
  -p 8080:8080 \
  -e KAFKA_BOOTSTRAP_SERVERS=broker1:9092,broker2:9092 \
  calinora/pilot:latest
```

## Environment Variables

Pass configuration via `-e` flags. Key variables:

```bash
docker run -d \
  --name pilot \
  -p 8080:8080 \
  -e KAFKA_BOOTSTRAP_SERVERS=broker1:9092,broker2:9092 \
  -e LOG_LEVEL=INFO \
  -e PILOT_BALANCE_THRESHOLD=5.0 \
  -e PILOT_THROTTLE_RATE_MB=50 \
  calinora/pilot:latest
```

See [Environment Variables](https://docs.calinora.io/configuration/environment-variables/) for the full list.

## Volume Mounts

Mount certificates for TLS/SASL connections:

```bash
docker run -d \
  --name pilot \
  -p 8080:8080 \
  -v /path/to/certs:/certs:ro \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
  -e KAFKA_SECURITY_PROTOCOL=SSL \
  -e KAFKA_SSL_CA_CERT_FILE=/certs/ca.pem \
  calinora/pilot:latest
```

For brokers that require a client certificate, add `KAFKA_SSL_CERT_FILE` and `KAFKA_SSL_KEY_FILE`. See [Mutual TLS](https://docs.calinora.io/configuration/tls/#mutual-tls-mtls).

## Health Checks

Configure Docker health checks using Pilot’s built-in endpoints:

```bash
docker run -d \
  --name pilot \
  -p 8080:8080 \
  --health-cmd="wget -q --spider http://localhost:8080/api/v1/health || exit 1" \
  --health-interval=10s \
  --health-timeout=5s \
  --health-retries=3 \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9092 \
  calinora/pilot:latest
```

| Endpoint | Purpose |
| - | - |
| `/api/v1/health` | Liveness - service is running |
| `/api/v1/ready` | Readiness - Kafka brokers are reachable |

## License Configuration

```bash
docker run -d \
  --name pilot \
  -p 8080:8080 \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9092 \
  -e LICENSE_STRING="${LICENSE_STRING}" \
  calinora/pilot:latest
```

Or use automatic license fetching:

```bash
-e LICENSE_FETCH_SUBSCRIPTION_ID=sub_123 \
-e LICENSE_FETCH_TOKEN=tok_abc
```

See [Licensing](https://docs.calinora.io/reference/licensing/) for details.

## Server TLS (HTTPS)

Serve HTTPS directly from Pilot:

```bash
docker run -d \
  --name pilot \
  -p 8443:8080 \
  -v /path/to/certs:/certs:ro \
  -e SERVER_TLS_ENABLED=true \
  -e SERVER_TLS_CERT_FILE=/certs/server.pem \
  -e SERVER_TLS_KEY_FILE=/certs/server-key.pem \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9092 \
  calinora/pilot:latest
```

## Networking

Pilot needs network access to:

- **Kafka brokers** on their advertised listener ports
- **License server** (optional) on HTTPS port 443 (`license.calinora.io`)
- **OAuth provider** (optional) on HTTPS port 443

Ensure the Docker network allows Pilot to reach Kafka brokers by their advertised hostnames.