Docker Deployment

Docker image

The GOVERN Probe image is published to Docker Hub as archetypal/govern-probe. Images are tagged by version and by latest.

# Pull latest stable
docker pull archetypal/govern-probe:latest

# Pull specific version
docker pull archetypal/govern-probe:1.2.0

Image architecture: linux/amd64, linux/arm64 (Apple Silicon compatible).

Basic run

docker run -d \
  --name govern-probe \
  --restart unless-stopped \
  -p 4020:4020 \
  -e GOVERN_API_KEY=gvn_live_xxxx \
  -e GOVERN_ORG_ID=org_xxxx \
  -e UPSTREAM_URL=https://api.anthropic.com \
  archetypal/govern-probe:latest

Production run with full options

docker run -d \
  --name govern-probe \
  --restart unless-stopped \
  -p 4020:4020 \
  -e GOVERN_API_KEY=gvn_live_xxxx \
  -e GOVERN_ORG_ID=org_xxxx \
  -e GOVERN_ENV=production \
  -e UPSTREAM_URL=https://api.anthropic.com \
  -e SCORING_MODE=flag \
  -e SCORING_SECURITY_THRESHOLD=0.7 \
  -e SCORING_BIAS_THRESHOLD=0.6 \
  -e TELEMETRY_FLUSH_INTERVAL_MS=5000 \
  -e TELEMETRY_BATCH_SIZE=50 \
  -v /etc/govern/config.yaml:/app/config/default.yaml:ro \
  --memory=256m \
  --cpus=0.5 \
  archetypal/govern-probe:latest

Using a config file

Mount a YAML configuration file to override environment variable defaults:

upstream:
  url: https://api.anthropic.com
  timeout_ms: 30000

scoring:
  mode: flag
  security:
    enabled: true
    threshold: 0.70
  bias:
    enabled: true
    threshold: 0.60
  accuracy:
    enabled: true
    threshold: 0.65
  drift:
    enabled: true
    baseline_window_hours: 168
  cost:
    enabled: true
    budget_tokens_per_hour: 500000

telemetry:
  flush_interval_ms: 5000
  batch_size: 50
  ring_buffer_size: 1000

docker run -d \
  -v /etc/govern/config.yaml:/app/config/default.yaml:ro \
  -e GOVERN_API_KEY=gvn_live_xxxx \
  -e GOVERN_ORG_ID=org_xxxx \
  archetypal/govern-probe:latest

Networking

Same machine (localhost)

Your app runs on the host, Probe in Docker:

docker run -d \
  -p 127.0.0.1:4020:4020 \
  -e UPSTREAM_URL=https://api.anthropic.com \
  ...

App environment: ANTHROPIC_BASE_URL=http://localhost:4020

Custom network (multi-container)

# Create network
docker network create govern-net

# Run probe on network
docker run -d \
  --name govern-probe \
  --network govern-net \
  -e UPSTREAM_URL=https://api.anthropic.com \
  ...

# Run your app on the same network
docker run -d \
  --name my-app \
  --network govern-net \
  -e ANTHROPIC_BASE_URL=http://govern-probe:4020 \
  my-app-image

Health checks

Docker supports native health checks. The Probe exposes /healthz:

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:4020/healthz || exit 1

Or via docker run:

docker run -d \
  --health-cmd="curl -f http://localhost:4020/healthz || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-start-period=10s \
  --health-retries=3 \
  ...

Logging

The Probe outputs structured JSON logs to stdout. Use Docker’s log drivers:

# Default (stdout)
docker logs govern-probe --follow

# JSON file with rotation
docker run -d \
  --log-driver json-file \
  --log-opt max-size=100m \
  --log-opt max-file=5 \
  ...

# Forward to syslog
docker run -d \
  --log-driver syslog \
  --log-opt syslog-address=udp://logs.example.com:514 \
  ...

Resource limits

The Probe is lightweight. Recommended minimums for production:

Resource	Minimum	Recommended
Memory	64MB	256MB
CPU	0.1 core	0.5 core
Disk	0 (ephemeral)	0

The Probe holds no durable state. All data is in-memory (ring buffer) or transmitted to GOVERN.

Upgrading

# Pull new image
docker pull archetypal/govern-probe:latest

# Stop and remove old container
docker stop govern-probe && docker rm govern-probe

# Start with same flags
docker run -d --name govern-probe ... archetypal/govern-probe:latest

Upgrades are zero-downtime when running multiple replicas behind a load balancer.