Advanced Docker Deployment

Docker Compose with Redis

For deployments where you need pool state to survive restarts, or where you want to run multiple replicas sharing a single IP pool. docker-compose.yml

services:
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --save 60 1
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

  proxy-hopper:
    image: ghcr.io/cams-data/proxy-hopper:latest-redis
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/etc/proxy-hopper/config.yaml:ro
    environment:
      PROXY_HOPPER_BACKEND: redis
      PROXY_HOPPER_REDIS_URL: redis://redis:6379/0
      PROXY_HOPPER_LOG_FORMAT: json
    depends_on:
      redis:
        condition: service_healthy

volumes:
  redis-data:

docker compose up -d

Scaling replicas

Because pool state lives in Redis, multiple replicas share it safely. Each IP is checked out to exactly one replica at a time via Redis BLPOP atomicity.

docker compose up -d --scale proxy-hopper=3

When scaling, remove the host ports: mapping from the proxy-hopper service and put a load balancer in front of the replicas.

Load balancing with Traefik

services:
  traefik:
    image: traefik:v3
    command:
      - "--providers.docker=true"
      - "--entrypoints.proxy.address=:8080"
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data

  proxy-hopper:
    image: ghcr.io/cams-data/proxy-hopper:latest-redis
    restart: unless-stopped
    # no ports: block — Traefik routes to it
    volumes:
      - ./config.yaml:/etc/proxy-hopper/config.yaml:ro
    environment:
      PROXY_HOPPER_BACKEND: redis
      PROXY_HOPPER_REDIS_URL: redis://redis:6379/0
      PROXY_HOPPER_LOG_FORMAT: json
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.proxy.entrypoints=proxy"
      - "traefik.http.services.proxy.loadbalancer.server.port=8080"
    deploy:
      replicas: 3

volumes:
  redis-data:

Enabling Prometheus metrics

Add the metrics port and environment variables to the proxy-hopper service:

proxy-hopper:
  ports:
    - "8080:8080"
    - "9090:9090"       # expose metrics port
  environment:
    PROXY_HOPPER_BACKEND: redis
    PROXY_HOPPER_REDIS_URL: redis://redis:6379/0
    PROXY_HOPPER_LOG_FORMAT: json
    PROXY_HOPPER_METRICS: "true"
    PROXY_HOPPER_METRICS_PORT: "9090"

Metrics are available at http://localhost:9090/metrics.

Enabling authentication

Mount a config file with auth: enabled. For configs containing credentials, use a Docker secret or pass the file from a secrets manager rather than committing it to source control:

proxy-hopper:
  image: ghcr.io/cams-data/proxy-hopper:latest-redis
  volumes:
    - ./config-with-auth.yaml:/etc/proxy-hopper/config.yaml:ro
  environment:
    PROXY_HOPPER_BACKEND: redis
    PROXY_HOPPER_REDIS_URL: redis://redis:6379/0

See API Key Authentication for the auth config format.

Memory backend — when Redis is overkill

For single-host deployments that don’t need multi-replica, you can use the simpler memory image even with Compose. Just skip Redis:

services:
  proxy-hopper:
    image: ghcr.io/cams-data/proxy-hopper:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/etc/proxy-hopper/config.yaml:ro

See Simple Docker Deployment for the single-container walkthrough.

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Advanced Docker Deployment

Docker Compose with Redis

Scaling replicas

Load balancing with Traefik

Enabling Prometheus metrics

Enabling authentication

Memory backend — when Redis is overkill

​Docker Compose with Redis

​Scaling replicas

​Load balancing with Traefik

​Enabling Prometheus metrics

​Enabling authentication

​Memory backend — when Redis is overkill

Docker Compose with Redis

Scaling replicas

Load balancing with Traefik

Enabling Prometheus metrics

Enabling authentication

Memory backend — when Redis is overkill