Coolify
Overview
Coolify is a self-hosted PaaS (Vercel/Netlify alternative) that deploys applications, databases, and services on your own infrastructure. It provides a REST API for programmatic control, supports multiple build packs, and uses Traefik for reverse proxy and SSL.
When to use: Deploying applications to self-hosted infrastructure, managing databases and services through API, automating deployments via CI/CD, self-hosting without vendor lock-in.
When NOT to use: Initial Coolify server installation (use the official install script via browser), managing Coolify's own infrastructure (Postgres, Redis — managed internally), or when a managed platform (Vercel, Railway) meets your needs without self-hosting requirements.
Quick Reference
| Pattern | Approach | Key Points |
|---|---|---|
| API auth | Authorization: Bearer <token> header | Token created in dashboard, scoped permissions |
| List applications | GET /api/v1/applications | Returns all apps with status and config |
| Trigger deploy | GET /api/v1/deploy?uuid=<app>&force=true | Or use per-app webhook URL |
| Create application | POST /api/v1/applications/public | Requires project_uuid, server_uuid, env_name |
| Update application | PATCH /api/v1/applications/<uuid> | Accepts build, health check, domain, limit fields |
| Auto-deploy | Enable in Advanced > General | Deploys on every push to configured branch |
| Webhook deploy | curl GET <webhook_url> -H "Authorization: Bearer..." | Controlled deploys from CI pipelines |
| GitHub Actions deploy | Build image, push to registry, trigger webhook | Full control over build + test before deploy |
| Nixpacks build | Auto-detected from source code | Zero-config for supported languages |
| Dockerfile build | Set build pack to dockerfile | Full control over build process |
| Compose build | docker-compose.yaml as source of truth | Multi-service stacks with Coolify labels |
| Environment variables | API or dashboard per-environment | Interpolated in Compose via ${VAR} syntax |
| Domain routing | fqdn field or Traefik labels in Compose | Automatic SSL via Let's Encrypt |
| Health checks | Configurable path, interval, retries via API | Required for running:healthy status |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| API returns "Unauthenticated" | Add Accept: application/json header alongside Bearer token |
| Can't read sensitive fields (auto-deploy, etc.) | Token needs view:sensitive or * permission scope |
| Auto-deploy not triggering | Verify GitHub App is connected and auto-deploy enabled in Advanced |
| Using API token without deploy permission | Token needs explicit deploy permission to trigger deployments |
| Health check fails on Compose services | Add exclude_from_hc: true label for non-HTTP services |
| Webhook deploy without auth header | Always include Authorization: Bearer <token> with webhook calls |
| Environment variables not available in build | Use build arguments in Advanced menu, not runtime env vars |
| Compose services can't communicate | Use service names as hostnames within the same stack network |
Delegation
- API exploration: Use
Exploreagent to discover existing Coolify resources - Dockerfile optimization: Use
Taskagent to review Dockerfiles for Coolify deployment - CI/CD pipeline design: Use
Planagent for deployment workflow strategy
If thedockerskill is available, delegate Dockerfile authoring, multi-stage builds, and image optimization to it. If thegithub-actionsskill is available, delegate workflow syntax and CI pipeline patterns to it. If theci-cd-architectureskill is available, delegate deployment strategy and environment promotion to it.