Health and operations

Probe matrix

Use liveness to restart a stuck process. Use readiness to decide whether it should receive traffic.

The transform and worker probes are service-local operator endpoints on ports 3002 and 3001. The bundled Compose files keep both ports on the private network, so /health/live and /health/ready on the public app or delivery hostname are expected to return 404. Run the probes inside their containers:

docker compose exec transform curl --fail --silent http://127.0.0.1:3002/health/live
docker compose exec transform curl --fail --silent http://127.0.0.1:3002/health/ready
docker compose exec worker node -e "fetch('http://127.0.0.1:3001/health/ready').then(r => { if (!r.ok) process.exit(1) })"

Workbench

Workbench is hosted by apps/worker and shows queue state, jobs, retries, and failures. It uses HTTP basic auth from KEENPIX_WORKBENCH_USERNAME and KEENPIX_WORKBENCH_PASSWORD. Coolify generates credentials automatically.

Workbench is an operator surface. Do not expose it without authentication, and prefer a private network, VPN, or access proxy.

Logs

docker compose logs --since=15m app
docker compose logs --since=15m transform
docker compose logs --since=15m worker

evlog writes structured output to the container terminal. Set KEENPIX_LOG_DIR only when you also mount a persistent directory and have a retention plan.

Failure order

1. Check docker compose ps for the first unhealthy dependency.
2. Check Postgres credentials and migrations.
3. Check transform readiness and available cache-disk space.
4. Check Dragonfly and worker queue connectivity.
5. Confirm KEENPIX_WORKER_SECRET matches between app, transform, and worker.
6. Confirm the origin host is allowed and resolvable from the transform container.

Back up Postgres before upgrades. Cache volumes are disposable; Postgres is not.