Docker

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

Image


docker pull calinora/pilot:latest

Pin to a specific version:


docker pull calinora/pilot:0.27.0

Basic Usage


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:


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 for the full list.

Volume Mounts

Mount certificates for TLS/SASL connections:


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.

Health Checks

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


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


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:


-e LICENSE_FETCH_SUBSCRIPTION_ID=sub_123 \
-e LICENSE_FETCH_TOKEN=tok_abc

See Licensing for details.

Server TLS (HTTPS)

Serve HTTPS directly from Pilot:


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.