Docker Compose guide

The shortest path to a working CapScope: one compose service, one named volume, one password. This guide covers the published image and a plain docker run, then hardens the setup with a read-only socket proxy and shows how to size the database.

Prerequisites

• A Docker host — any machine with the Docker Engine and its socket available.
• A long random password for Basic auth: openssl rand -base64 24.
• Outbound internet on the host if you build from source (the first build downloads Go modules).
• A TLS-terminating reverse proxy in production — CapScope listens on 8080 with plain HTTP.

Quick start with docker run

docker run -d --name capscope \
  -p 8080:8080 \
  -e AUTH_USER=admin \
  -e AUTH_PASS='change-me' \
  -v capscope-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --restart unless-stopped \
  ghcr.io/hacrex/capscope:latest

Open http://localhost:8080 and log in. The named volume capscope-data holds the SQLite database at /data/capscope.db — do not drop it, or history dies with the container.

Docker Compose

services:
  capscope:
    image: ghcr.io/hacrex/capscope:latest
    ports:
      - "8080:8080"
    environment:
      AUTH_USER: admin
      AUTH_PASS: change-me
      # LOG_RETENTION: 7d
      # MAX_DB_MB: 2048
      # EXCLUDE: '^captain-'
    volumes:
      - capscope-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

volumes:
  capscope-data:

AUTH_PASS defaults to change-me — change it before exposing the port. The repo also ships deploy/docker-compose.yml, which builds from source (build: ..) instead of pulling the published image:

cd deploy
docker compose up -d --build   # then open http://<host>:8080

Harden with a socket proxy

Mounting the socket is the simplest setup, but a read-only socket proxy keeps the raw socket out of CapScope entirely. Add a tecnativa/docker-socket-proxy service that exposes only the read endpoints CapScope needs, drop the socket mount from CapScope, and point DOCKER_HOST at the proxy:

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment: { CONTAINERS: 1, EVENTS: 1, PING: 1, POST: 0 }
    volumes: ["/var/run/docker.sock:/var/run/docker.sock:ro"]

# capscope: drop the docker.sock mount and set:
#   DOCKER_HOST=tcp://socket-proxy:2375

CONTAINERS=1 is what allows GET /containers/* — inspect, logs and stats. POST=0 blocks every write. Do not publish the proxy's port publicly; keep it on the same Docker network as CapScope.

Environment highlights

Everything is configured through environment variables. The full list lives in the configuration reference; these are the ones you almost always touch on a Docker host:

Verify

Troubleshooting

Capacity

Measured on a sandbox: about 400 bytes of database per stored log line for a 130-byte JSON line (three indexes included). Estimate with bytes per day = lines per second × 86400 × 400:

Metrics are cheap: one row per container every 10 seconds is roughly 8,600 rows per container per day. Set MAX_DB_MB to fit your volume — the oldest logs are dropped early to stay under the cap.

Next: platform-specific steps for CapRover, Coolify, Dokploy, Dokku or Portainer & others.