HomeGuidesCoolify

Coolify guide

Coolify builds the repo's Dockerfile directly, so no extra definition file is needed. Create a Dockerfile resource, add one persistent volume at /data, give CapScope a way to reach the Docker Engine API, and put a domain with HTTPS in front of port 8080.

Create the resource

New Resource → Dockerfile

In your Coolify project, choose New Resource → Dockerfile and point it at the CapScope repository.

Confirm the build context

Coolify builds the Dockerfile at the repo root automatically; set Build context to . if it asks. The first build downloads Go modules, so the host needs outbound internet.

Configure it

Environment variables

Key	Value
`AUTH_USER`	`admin`, or your username
`AUTH_PASS`	a long random password — required, the server refuses to start without it
`MAX_DB_MB`	size cap for live data, for example `2048`
`EXCLUDE`	optional; `^coolify-` hides Coolify's own containers from the sidebar

You do not need to add Traefik labels by hand — com.traefik.* is not required here, Coolify adds the routing itself.

Ports, domain and health check

Setting	Value
Container port	`8080`
Domain	assign the app a Domain in Coolify and turn on HTTPS
Health check	URL path `/healthz` — auth-free by design, so Coolify can probe it without secrets

Do not expose the app on plain HTTP. Basic auth credentials travel in clear text without TLS. Enable HTTPS on the domain before pointing anyone at it.

Storage

Add a Persistent Storage volume to the resource:

Path in container	Label
`/data`	`capscope-data` — the SQLite database lives here

Without the volume, history is lost. Logs, crash snapshots and settings are wiped on each redeploy if /data is not persisted.

Docker access

CapScope needs to reach the Docker Engine API of the host. Two options:

Socket proxy (recommended)

Deploy the tecnativa/docker-socket-proxy snippet from deploy/docker-compose.yml on the same network (or as a second "Docker Compose" resource), with CONTAINERS=1, EVENTS=1, PING=1, POST=0. Then add to CapScope:

environment

DOCKER_HOST=tcp://<service-name-of-proxy>:2375

This keeps the raw socket out of CapScope entirely: the proxy exposes only the read endpoints CapScope needs, and POST=0 blocks every write.

Socket mount

In the resource's run-time config, bind /var/run/docker.sock from the host. Simpler, but this gives the container root-equivalent access to the host — only use it on single-user hosts.

Why the container runs as root. That is deliberate: the docker.sock mount needs it. The socket-proxy variant removes the need for the mount.

Notes

Instance count: one. Never scale Coolify to more than one replica of CapScope — each instance would write the same SQLite file and corrupt it.
Live tail (SSE). CapScope sends X-Accel-Buffering: no, which Nginx proxies respect; Traefik and Caddy stream it as-is. If the live view stalls, check the proxy in front of the instance for response buffering on /api/logs/stream.
Retention. Logs default to 7 days and crash snapshots to 30 days; MAX_DB_MB caps the database and drops the oldest logs first. See the configuration reference for every variable.