Coolify (Self-Hosted PaaS)

1. Concept Overview & Systemic Problem

Cloud PaaS platforms (Vercel, Heroku, Netlify, Render) have provided developers with unparalleled comfort: a simple git push automatically builds the project, allocates a domain, connects SSL, and deploys the service. However, this comfort comes at a financial cost and strict architectural constraints:

• Exorbitant Billing: Cloud traffic costs can be 10–20 times higher than market rates, with overage bills reaching thousands of dollars.
• Serverless Timeouts: Function execution limits (15–60 seconds) make it impossible to run autonomous agent cycles, complex scraping, or long deliberations of language models.
• Vendor Lock-in: Specific optimizations complicate the migration of code to on-premises hardware.

Coolify offers the best of both worlds: the Vercel experience on your own server for $5–$20 per month. This open-source server management system (Self-Hosted PaaS) installs with a single command, connects to GitHub/GitLab repositories, and manages the entire cycle of building, traffic routing, and database administration.

2. Architectural Taxonomy & Mental Model

The architectural framework of Coolify is based on orchestrating the Docker daemon and a dynamic proxy:

┌─────────────────────────────────────────────────────────────┐
│                    COOLIFY HOST ARCHITECTURE                │
├─────────────────────────────────────────────────────────────┤
│ 1. Dynamic Reverse Proxy (Traefik v3 Core Engine)           │
│    • Automatic port routing via Docker Labels                │
│    • Automatic Let's Encrypt SSL certificates (ACME)         │
├─────────────────────────────────────────────────────────────┤
│ 2. Coolify Control Plane (Laravel API & Live Web UI)        │
│    • GitHub / GitLab webhook manager                          │
│    • Environment variable management (.env encryption)       │
├─────────────────────────────────────────────────────────────┤
│ 3. Polyglot Build Engine:                                   │
│    • Nixpacks (Auto-detection of languages: Node, Bun, Python, Go) │
│    • Dockerfile / Docker Compose Builder                    │
├─────────────────────────────────────────────────────────────┤
│ 4. Managed Datastores & Storage (Postgres, Redis, S3 Backup)│
└─────────────────────────────────────────────────────────────┘

1. Dynamic Reverse Proxy (Traefik Engine):
   • The central dispatcher of incoming traffic. It constantly listens to the Docker socket: when a new container with domain labels is launched, Traefik instantly picks it up, issues an SSL certificate, and begins routing HTTP/HTTPS requests without restarting the proxy.
2. Universal Build Engine (Nixpacks & Docker):
   • Facilitates code builds without the need to manually write complex Dockerfile. Nixpacks automatically detects the Node.js version, installs dependencies via pnpm, and generates a minimal container.
3. One-Click Data Management (Managed Databases):
   • Deploys production instances of PostgreSQL, Redis, MySQL, ClickHouse, or MinIO with automatic encrypted backups to S3 cloud storage (AWS or Cloudflare R2) on a schedule.
4. Environment Isolation (Preview Deployments):
   • Automatically spins up separate ephemeral copies of the service for each open Pull Request on temporary subdomains.

3. Technical Pipeline & Internal Mechanics

The continuous deployment lifecycle (GitOps Lifecycle) in Coolify:

1. Code Commit and Webhook: An engineer performs a git push origin main. GitHub sends a signed HMAC webhook to the Coolify API.
2. Validation and Worker Launch: Coolify verifies the security signature, fetches the latest commit by the specified SHA hash, and launches an isolated build container.
3. Build Phase (Nixpacks Build): Dependencies are installed, the application build (npm run build) is executed. An optimized working Docker image is created.
4. Seamless Traffic Switching (Rolling Deployment):
   • A new container with the application is launched on a new internal port.
   • Traefik performs a health check.
   • Once the new container responds with HTTP 200, the proxy switches traffic, and the old container is stopped (Zero-Downtime Swap).
5. Alerting and Notifications: The status of the successful deployment is sent to the engineer via Telegram or Discord with a link to the commit.

4. Production Engineering Scenarios

01. Deploying a Next.js 15 Full-Stack Platform on a $10 Server

A complete launch of a commercial SaaS on a VPS at Hetzner:

• Coolify builds the Next.js frontend, spins up PostgreSQL and Redis for session caching.
• Traffic flows through the built-in Traefik with HTTP/2 and SSL support.
• The service handles one million views per month with zero additional cloud costs.

02. Hosting Long-Running AI Agents Without Timeouts

Deploying complex backend processes (LangGraph, auto-scraping):

• On Vercel, requests time out after 60 seconds.
• In Coolify, the agent can run autonomously for 4 hours in a background container, maintaining open WebSocket connections with the client.

03. Creating Temporary Preview Environments (PR Previews)

Facilitating comfortable reviews for the team:

• When PR #87 is opened, Coolify automatically spins up the application at pr-87.gotburnout.dev.
• The tester checks functionality live before merging into the main branch, after which the container is automatically removed upon closing the PR.

5. Pitfalls, Common Mistakes & Security

• Server Crashes Due to Memory Overflow (Build OOM): Building modern frontend projects on Next.js can consume up to 3–4 GB of RAM during bundle optimization. On servers with 2 GB of RAM, ensure to create a swap file (swapfile) of at least 4 GB.
• Leaving the Management Panel Open to Scanners: By default, the Coolify interface runs on port 8000. Be sure to secure it with your own domain and enforce two-factor authentication (2FA), or block it with UFW firewall, allowing traffic only through Tailscale/VPN.
• Disk Space Overflow from Old Docker Images: Daily deployments create dozens of compiled layers. If automatic cleanup (Docker Cleanup Scheduler) is not enabled, the disk will fill up within weeks.
• Storing Database Passwords in Unsecured Files: Use the built-in secret manager of Coolify to inject environment variables instead of committing .env files to the repository.