Runbook: Coolify deployment
Service overview
Section titled “Service overview”Coolify v4 manages all container deployments on the Hetzner VPS. The GitHub Actions release workflow triggers deploys via the Coolify deploy webhook API. Operator accesses Coolify UI at the configured COOLIFY_API_URL.
Symptoms → Diagnosis → Fix
Section titled “Symptoms → Diagnosis → Fix”Deploy webhook returns 401
Section titled “Deploy webhook returns 401”Diagnosis
COOLIFY_DEPLOY_TOKEN(GH secret) does not match thekc-ci-deploytoken in Coolify.
Fix
- Regenerate the
kc-ci-deploytoken in Coolify UI → Teams → API Tokens. - Update the
COOLIFY_DEPLOY_TOKENGitHub Actions secret.
Container fails to start after deploy
Section titled “Container fails to start after deploy”Diagnosis
- Coolify UI → Application → Deployment → Logs.
- Common: missing env var, wrong image tag, DB not reachable.
Fix
- Missing env var: add it in Coolify UI → Application → Environment Variables; redeploy.
- Wrong image: check GHCR for the expected tag; ensure
IMAGE_TAGis set correctly. - DB unreachable: check postgres container is healthy; check PgBouncer.
Coolify itself is down
Section titled “Coolify itself is down”Diagnosis
- SSH into the Hetzner VPS (operator action).
docker ps— check if the Coolify container is running.
Fix
- Restart Coolify:
docker restart coolify. - If VPS is unreachable: operator action — Hetzner console.
- Coolify backups are in R2 bucket
coolify-host-schne-id— do not delete.
Rollback a bad deploy
Section titled “Rollback a bad deploy”Fix
- Coolify UI → Application → Deployments → select a previous successful deployment → Redeploy.
- Or: push a revert commit to
main— the release workflow will rebuild and redeploy.
Environment variable management
Section titled “Environment variable management”Coolify is the source of truth for runtime env vars (injected as container env). The encrypted secrets.{env}.env.age files in the repo are the sealed reference — operator decrypts with bun run secrets show {env} to verify.