coolify

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