HomeGuidesDokploy

Deploying CapScope on Dokploy

Dokploy deploys from either a Dockerfile or a Docker Compose file. The compose path is recommended here because it also wires the Docker socket in one go — and gives you the named volume for the SQLite database by default.

What Dokploy needs from the repo: the root Dockerfile (or deploy/docker-compose.yml), an EXPOSE 8080, a VOLUME /data and the unauthenticated /healthz probe. All of them ship in the repository — nothing platform-specific is required.

1. Create the service

Create a Docker Compose service

Project → Create Service → Docker Compose. Point it at this repository and set the compose path to deploy/docker-compose.yml.

Let the first build finish

The compose file builds from the repo root (build: ..), so the first deploy compiles the Go binary. The Dokploy server needs outbound internet during the build to download Go modules.

Or use a Dockerfile service

Quick alternative with no compose file: create a Dockerfile service and add the volume mounts listed below in the service's Advanced / Volumes section.

2. Environment variables

Set these in the service's Environment tab:

Key	Value
`AUTH_USER`	`admin`, or your username.
`AUTH_PASS`	A long random password — `openssl rand -base64 24`.
`MAX_DB_MB`	Size cap for live data, for example `2048`.
`EXCLUDE`	Optional; hide Dokploy's own containers, for example `^dkp-`.

The compose file defaults AUTH_PASS to change-me — change it before exposing the app. The server refuses to start without a password at all.

deploy/docker-compose.yml (essentials)

services:
  capscope:
    build: ..
    ports: ["8080:8080"]
    environment:
      AUTH_PASS: change-me   # change this
      MAX_DB_MB: 2048
    volumes:
      - capscope-data:/data
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  capscope-data:

3. Domain and TLS

Add a Domain to the service — Dokploy routes it through its bundled Traefik — bound to container port 8080.
Enable HTTPS / Let's Encrypt. Do not expose the app on plain HTTP: Basic auth credentials travel in clear text.
SSE works behind Traefik as-is. CapScope also sends X-Accel-Buffering: no for Nginx-style proxies, so the live tail streams even through buffers.

4. Storage

The compose file already declares a named volume capscope-data mounted at /data. Keep it — the SQLite database lives there, and without persistence history, crash snapshots and settings are lost on every redeploy.

Path in container	Volume
`/data`	`capscope-data` — SQLite database, alert rules, checkpoints
`/var/run/docker.sock`	host socket (or drop it and use a socket proxy)

Health check: in the service settings, set the HTTP health check path to /healthz (auth-free by design). The image also carries a Docker HEALTHCHECK with the same probe.

5. Socket proxy (recommended)

Mounting docker.sock is root equivalent on the host. To limit what CapScope can do:

Deploy the proxy

Add tecnativa/docker-socket-proxy as a Docker Compose resource on the same network with CONTAINERS=1, EVENTS=1, PING=1, POST=0. Do not map any public port.

Point CapScope at it

Remove the socket mount from the CapScope service and set DOCKER_HOST=tcp://<proxy-service-name>:2375.

Verify

CapScope only issues GET requests, so POST=0 stays safe. If it fails to start on your proxy image version, check that CONTAINERS=1 is applied — proxy defaults vary between image releases.

6. Notes and caveats

Caveat	What to do
Single node only	Dokploy runs on Docker Swarm. CapScope reads the host's Docker socket, so in a multi-node Swarm it only sees containers on the node its task lands on. Pin it to the manager or wherever your workloads run.
One replica	Never scale the capscope service beyond 1 — instances would write the same SQLite file.
Storage	Keep the named volume `capscope-data` at `/data`.
Runs as root	On purpose — `docker.sock` needs it. Use the socket-proxy variant to drop the mount instead.
Log drivers	`json-file`, `local` and `journald` are supported. If a container shows no logs, `docker logs` failing for it is the tell.

7. Verify

Log in

Open your domain, authenticate with AUTH_USER/AUTH_PASS. The header chip should show a container count above zero.

Crash it on purpose

Run a throwaway container that exits with code 1 and check the Crashes tab for a snapshot with exit code, last lines and summary.

Record a deploy

Use Record deploy in the Metrics tab, or POST /api/deploys from CI, then confirm the marker appears on the charts.

Troubleshooting

Symptom	Likely cause
Exits at start: `AUTH_PASS is required`	Set `AUTH_PASS` in the service environment (or `ALLOW_NO_AUTH=true` for a private test).
Exits at start: `cannot reach Docker`	Socket not mounted, or the `DOCKER_HOST` proxy URL is wrong.
App list empty	`INCLUDE`/`EXCLUDE` regexes filtering everything, or no containers on this node.
Live view stalls behind the proxy	Response buffering on `/api/logs/stream` — disable it for that path.
History gone after redeploy	The `/data` volume was not attached.