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
Explore agent to discover existing Coolify resources
- Dockerfile optimization: Use
Task agent to review Dockerfiles for Coolify deployment
- CI/CD pipeline design: Use
Plan agent for deployment workflow strategy
If the docker skill is available, delegate Dockerfile authoring, multi-stage builds, and image optimization to it.
If the github-actions skill is available, delegate workflow syntax and CI pipeline patterns to it.
If the ci-cd-architecture skill is available, delegate deployment strategy and environment promotion to it.
References
- API: authentication, endpoints, common operations, and permission scopes
- Deployment: auto-deploy, webhooks, GitHub Actions, and CI/CD pipelines
- Build packs: Nixpacks, Dockerfile, Compose conventions, and configuration
1---
2name: coolify
3description: |
4 Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration.
5
6 Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
7license: MIT
8metadata:
9 author: oakoss
10 version: '1.0'
11 source: 'https://coolify.io/docs'
12user-invocable: false
13---
14
15# Coolify
16
17## Overview
18
19Coolify 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.
20
21**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.
22
23**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.
24
25## Quick Reference
26
27| Pattern | Approach | Key Points |
28| --------------------- | ------------------------------------------------------- | ------------------------------------------------- |
29| API auth | `Authorization: Bearer <token>` header | Token created in dashboard, scoped permissions |
30| List applications | `GET /api/v1/applications` | Returns all apps with status and config |
31| Trigger deploy | `GET /api/v1/deploy?uuid=<app>&force=true` | Or use per-app webhook URL |
32| Create application | `POST /api/v1/applications/public` | Requires project_uuid, server_uuid, env_name |
33| Update application | `PATCH /api/v1/applications/<uuid>` | Accepts build, health check, domain, limit fields |
34| Auto-deploy | Enable in Advanced > General | Deploys on every push to configured branch |
35| Webhook deploy | `curl GET <webhook_url> -H "Authorization: Bearer ..."` | Controlled deploys from CI pipelines |
36| GitHub Actions deploy | Build image, push to registry, trigger webhook | Full control over build + test before deploy |
37| Nixpacks build | Auto-detected from source code | Zero-config for supported languages |
38| Dockerfile build | Set build pack to `dockerfile` | Full control over build process |
39| Compose build | `docker-compose.yaml` as source of truth | Multi-service stacks with Coolify labels |
40| Environment variables | API or dashboard per-environment | Interpolated in Compose via `${VAR}` syntax |
41| Domain routing | `fqdn` field or Traefik labels in Compose | Automatic SSL via Let's Encrypt |
42| Health checks | Configurable path, interval, retries via API | Required for `running:healthy` status |
43
44## Common Mistakes
45
46| Mistake | Correct Pattern |
47| ----------------------------------------------- | ------------------------------------------------------------------ |
48| API returns "Unauthenticated" | Add `Accept: application/json` header alongside Bearer token |
49| Can't read sensitive fields (auto-deploy, etc.) | Token needs `view:sensitive` or `*` permission scope |
50| Auto-deploy not triggering | Verify GitHub App is connected and auto-deploy enabled in Advanced |
51| Using API token without deploy permission | Token needs explicit `deploy` permission to trigger deployments |
52| Health check fails on Compose services | Add `exclude_from_hc: true` label for non-HTTP services |
53| Webhook deploy without auth header | Always include `Authorization: Bearer <token>` with webhook calls |
54| Environment variables not available in build | Use build arguments in Advanced menu, not runtime env vars |
55| Compose services can't communicate | Use service names as hostnames within the same stack network |
56
57## Delegation
58
59- **API exploration**: Use `Explore` agent to discover existing Coolify resources
60- **Dockerfile optimization**: Use `Task` agent to review Dockerfiles for Coolify deployment
61- **CI/CD pipeline design**: Use `Plan` agent for deployment workflow strategy
62
63> If the `docker` skill is available, delegate Dockerfile authoring, multi-stage builds, and image optimization to it.
64> If the `github-actions` skill is available, delegate workflow syntax and CI pipeline patterns to it.
65> If the `ci-cd-architecture` skill is available, delegate deployment strategy and environment promotion to it.
66
67## References
68
69- [API: authentication, endpoints, common operations, and permission scopes](references/api-patterns.md)
70- [Deployment: auto-deploy, webhooks, GitHub Actions, and CI/CD pipelines](references/deployment-strategies.md)
71- [Build packs: Nixpacks, Dockerfile, Compose conventions, and configuration](references/build-packs.md)
oakoss