Docker Compose Quickstart

Docker Compose is the fastest way to run GOVERN. Use it for local development, proof-of-concept deployments, or small teams.

Prerequisites

Docker 24+
Docker Compose 2.20+
4 GB free RAM
20 GB free disk space

Quickstart

# Download docker-compose.yml
curl -O https://releases.govern.archetypal.ai/latest/docker-compose.yml
curl -O https://releases.govern.archetypal.ai/latest/.env.example

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Start GOVERN
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f govern-api

GOVERN is available at http://localhost:3000 within ~60 seconds.

docker-compose.yml

version: '3.9'

services:
  govern-api:
    image: archetypal/govern-api:latest
    restart: unless-stopped
    ports:
      - "3001:3001"
    env_file: .env
    environment:
      - DATABASE_URL=postgresql://govern:${POSTGRES_PASSWORD}@postgres:5432/govern
      - REDIS_URL=redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - govern-data:/data

  govern-app:
    image: archetypal/govern-app:latest
    restart: unless-stopped
    ports:
      - "3000:80"
    environment:
      - API_URL=http://govern-api:3001

  govern-probe:
    image: archetypal/govern-probe:latest
    restart: unless-stopped
    environment:
      - GOVERN_API_URL=http://govern-api:3001
      - GOVERN_API_KEY=${GOVERN_API_KEY}
    network_mode: host  # Required for transparent proxy

  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=govern
      - POSTGRES_USER=govern
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U govern"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "--no-auth-warning", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  govern-data:
  postgres-data:
  redis-data:

Environment Variables (.env)

# GOVERN
GOVERN_LICENSE_KEY=your-license-key
GOVERN_API_KEY=your-api-key           # Set this to a secure random string
GOVERN_SECRET_KEY=your-secret-key    # JWT signing key

# Database
POSTGRES_PASSWORD=change-me-in-production

# Redis
REDIS_PASSWORD=change-me-in-production

# Auth (optional — remove for dev, required for production)
AUTH_PROVIDER=local                   # local | saml | oidc
SESSION_TIMEOUT=28800                 # 8 hours in seconds

# Notifications (optional)
SLACK_WEBHOOK_URL=
PAGERDUTY_API_KEY=

Common Operations

# Stop GOVERN
docker compose down

# Update to latest version
docker compose pull
docker compose up -d

# Run migrations manually
docker compose exec govern-api npx govern-migrate up

# Reset all data (destructive)
docker compose down -v
docker compose up -d

# View resource usage
docker stats govern-api govern-app postgres redis

Enabling TLS

For production Docker Compose deployments, add an Nginx TLS terminator:

nginx:
  image: nginx:alpine
  restart: unless-stopped
  ports:
    - "80:80"
    - "443:443"
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf
    - /etc/letsencrypt:/etc/letsencrypt:ro