Tutorial: Running Gateway with Docker Compose

This tutorial walks you through deploying the Keeptrusts gateway using Docker Compose for production-style environments. You will configure environment variables, mount policy configs via volumes, set up health checks, configure logging, and scale to multiple replicas.

Use this page when

You are deploying the Keeptrusts gateway as a Docker container in production.
You need to configure environment variables, volume-mounted policy configs, and health checks.
You want to scale the gateway to multiple replicas behind a load balancer.
You are setting up structured JSON logging and restart policies for container orchestration.

Primary audience

Primary: DevOps and platform engineers containerising gateway deployments
Secondary: SRE teams configuring health checks and scaling; security teams reviewing container secrets handling

Prerequisites

Docker and Docker Compose installed
An OpenAI-compatible API key
A Keeptrusts API instance (for event forwarding)
A policy-config.yaml file ready (see gateway first run)

Step 1: Create the Project Directory

mkdir keeptrusts-gateway && cd keeptrusts-gateway

Create the policy configuration that the gateway container will use:

pack:
  name: docker-compose-demo
  version: 0.1.0
  enabled: true

providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-4o-mini
      base_url: https://api.openai.com
      secret_key_ref:
        env: OPENAI_API_KEY

policies:
  chain:
    - pii-detector
    - audit-logger

policy:
  pii-detector:
    action: redact
  audit-logger:
    retention_days: 365

Step 2: Create the Environment File

Create an .env file with runtime secrets (never commit this to version control):

# .env
OPENAI_API_KEY=sk-your-openai-key-here
KEEPTRUSTS_API_URL=http://keeptrusts-api:8080
KEEPTRUSTS_GATEWAY_TOKEN=kt_api_token_here
GATEWAY_LISTEN=0.0.0.0:41002
KEEPTRUSTS_LOG_LEVEL=info
KEEPTRUSTS_LOG_FORMAT=json

Step 3: Create the Docker Compose File

# docker-compose.yml
services:
  keeptrusts-gateway:
    image: ghcr.io/keeptrusts/gateway:latest
    container_name: keeptrusts-gateway
    restart: unless-stopped
    ports:
      - "41002:41002"
    env_file:
      - .env
    environment:
      - RUST_LOG=${KEEPTRUSTS_LOG_LEVEL:-info}
      - KEEPTRUSTS_LOG_FORMAT=${KEEPTRUSTS_LOG_FORMAT:-json}
    command:
      - gateway
      - run
      - --listen
      - ${GATEWAY_LISTEN:-0.0.0.0:41002}
      - --policy-config
      - /etc/keeptrusts/policy-config.yaml
    volumes:
      - ./config/policy-config.yaml:/etc/keeptrusts/policy-config.yaml:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:41002/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 5s
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"
        tag: "keeptrusts-gateway"
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
        reservations:
          memory: 128M
          cpus: "0.25"
    networks:
      - keeptrusts

networks:
  keeptrusts:
    driver: bridge

Step 4: Start the Gateway

docker compose up -d

Check the container status:

docker compose ps

Expected output:

NAME                  IMAGE                              STATUS                   PORTS
keeptrusts-gateway    ghcr.io/keeptrusts/gateway:latest  Up 15 seconds (healthy)  0.0.0.0:41002->41002/tcp

View startup logs:

docker compose logs keeptrusts-gateway

keeptrusts-gateway  | {"timestamp":"2026-04-23T12:00:01Z","level":"INFO","message":"Loaded 1 provider(s), 2 policy(ies)"}
keeptrusts-gateway  | {"timestamp":"2026-04-23T12:00:01Z","level":"INFO","message":"Gateway ready","port":41002}

Step 5: Test the Running Gateway

curl -s http://localhost:41002/health | jq .

{
  "status": "healthy",
  "version": "0.25.0",
  "uptime_seconds": 42,
  "providers": [{"name": "openai", "status": "reachable"}],
  "policies": 2
}

Send a test request:

curl -s http://localhost:41002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello from Docker!"}]
  }' | jq '.choices[0].message.content'

Step 6: Configure Logging for Production

For structured JSON logging with a log aggregator, update the compose file:

    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "10"
        tag: "{{.Name}}"
        labels: "service"
      labels:
        service: keeptrusts-gateway

Or forward to an external logging system using a syslog or fluentd driver:

    logging:
      driver: fluentd
      options:
        fluentd-address: "localhost:24224"
        tag: "keeptrusts.gateway"

Step 7: Scale to Multiple Replicas

For high-availability, scale the gateway behind a load balancer:

# docker-compose.yml
services:
  keeptrusts-gateway:
    image: ghcr.io/keeptrusts/gateway:latest
    restart: unless-stopped
    expose:
      - "41002"
    env_file:
      - .env
    environment:
      - RUST_LOG=${KEEPTRUSTS_LOG_LEVEL:-info}
      - KEEPTRUSTS_LOG_FORMAT=${KEEPTRUSTS_LOG_FORMAT:-json}
    command:
      - gateway
      - run
      - --listen
      - ${GATEWAY_LISTEN:-0.0.0.0:41002}
      - --policy-config
      - /etc/keeptrusts/policy-config.yaml
    volumes:
      - ./config/policy-config.yaml:/etc/keeptrusts/policy-config.yaml:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:41002/health"]
      interval: 10s
      timeout: 5s
      retries: 3
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 512M
    networks:
      - keeptrusts

  nginx:
    image: nginx:alpine
    ports:
      - "41002:41002"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      keeptrusts-gateway:
        condition: service_healthy
    networks:
      - keeptrusts

networks:
  keeptrusts:
    driver: bridge

Create a minimal nginx.conf:

# nginx.conf
events { worker_connections 1024; }

http {
  upstream gateway {
    server keeptrusts-gateway:41002;
  }

  server {
    listen 41002;

    location / {
      proxy_pass http://gateway;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_read_timeout 120s;
    }

    location /health {
      proxy_pass http://gateway/health;
    }
  }
}

Start the scaled deployment:

docker compose up -d --scale keeptrusts-gateway=3

Step 8: Update Configuration in Docker Compose

To apply a config change in Docker Compose:

Edit config/policy-config.yaml
Restart the gateway container:

docker compose restart keeptrusts-gateway

The gateway starts again with the updated configuration mounted from config/policy-config.yaml.

Step 9: Monitor Container Health

Check the health status of all replicas:

docker compose ps --format json | jq '{name: .Name, state: .State, health: .Health}'

View real-time logs across replicas:

docker compose logs -f keeptrusts-gateway --tail 50

For AI systems

Canonical terms: Keeptrusts gateway, Docker Compose, container deployment, health check, replica scaling, volume mount, environment file.
Docker image: ghcr.io/keeptrusts/gateway:latest.
Runtime inputs: KEEPTRUSTS_API_URL, KEEPTRUSTS_GATEWAY_TOKEN, OPENAI_API_KEY, KEEPTRUSTS_LOG_LEVEL, KEEPTRUSTS_LOG_FORMAT; Compose uses GATEWAY_LISTEN to build the kt gateway run --listen command.
Best next pages: Gateway Health Monitoring, Config Hot Reload, Multi-Gateway.

For engineers

Prerequisites: Docker + Docker Compose, provider API key, Keeptrusts API instance, prepared policy-config.yaml.
Never commit .env files with secrets to version control.
Health check: curl -f http://localhost:41002/health with interval: 30s, timeout: 10s, retries: 3.
Scale: docker compose up --scale keeptrusts-gateway=3 for horizontal scaling.
Logs: set KEEPTRUSTS_LOG_FORMAT=json for structured log aggregation; use docker compose logs -f keeptrusts-gateway to tail.

For leaders

Docker Compose deployment provides a reproducible, portable gateway setup suitable for staging and production.
Replica scaling enables horizontal capacity growth without changing the policy config.
Container health checks integrate with orchestrators (Kubernetes, ECS) for automatic restart on failure.
Secrets stay in .env files or Docker secrets — never baked into images.

Next steps

Multi-Gateway — multi-team hosted gateway topology with Docker Compose
Gateway Health Monitoring — Prometheus metrics and alerting for containers
CORS & IP Allowlist — production network security for containerised gateways

Use this page when​

Primary audience​

Prerequisites​

Step 1: Create the Project Directory​

Step 2: Create the Environment File​

Step 3: Create the Docker Compose File​

Step 4: Start the Gateway​

Step 5: Test the Running Gateway​

Step 6: Configure Logging for Production​

Step 7: Scale to Multiple Replicas​

Step 8: Update Configuration in Docker Compose​

Step 9: Monitor Container Health​

For AI systems​

For engineers​

For leaders​

Next steps​