Coolify: The Complete Guide to Self-Hosted PaaS Deployment

Deploy apps on your own server with the ease of Heroku — install Coolify, connect Git, configure domains, manage databases, automate CI/CD and scale across multiple servers, all while keeping full control of your data.

1. What Is Coolify?

Coolify is an open-source, self-hosted Platform-as-a-Service (PaaS) that gives you a Heroku/Vercel-like experience on your own server. Built with Laravel + Docker, it provides a dashboard for deploying applications, managing databases, setting up domains with automatic TLS, and wiring up Git-based CI/CD — all without vendor lock-in.

Core concepts

  • Projects & Environments — Organize apps into projects, each with environments (production, staging, dev).
  • Resources — Applications (web apps, APIs), databases (PostgreSQL, MySQL, Redis, MongoDB), and services (MinIO, etc.).
  • Servers — Physical or virtual machines that run your workloads. Coolify connects via SSH.
  • Build Packs — Nixpacks (auto-detect), Dockerfile, Docker Compose, or static site builds.
  • Proxy — Traefik (default) or Caddy for routing, load balancing and TLS.

2. Why Choose Coolify?

  • Zero vendor lock-in — Your server, your data, your rules.
  • Predictable costs — Fixed VPS price vs. variable cloud billing.
  • One-click services — Spin up PostgreSQL, Redis, MinIO, etc. with a single click.
  • Auto-deploy from Git — Push to a branch and Coolify builds + deploys automatically.
  • Free TLS — Automatic Let's Encrypt certificates for every domain.
  • Multi-server — Manage multiple servers from one dashboard.
  • Active community — Open-source with active development and Discord support.

When Coolify might NOT be the right choice

  • You need auto-scaling across dozens of nodes (consider Kubernetes instead).
  • You have zero tolerance for operational responsibility (stick with fully managed PaaS).
  • Your compliance framework requires specific managed-service certifications (SOC 2, HIPAA) that only cloud providers offer natively.

3. Architecture Overview

┌─────────────────────────────────┐
│         Your Browser            │
│   (Coolify Dashboard / API)     │
└───────────┬─────────────────────┘
            │ HTTPS
┌───────────▼─────────────────────┐
│   Coolify Control Plane         │
│   (Laravel app + PostgreSQL)    │
│   SSH Agent  ·  Build Worker    │
└───────────┬─────────────────────┘
            │ SSH
┌───────────▼─────────────────────┐
│   Target Server(s)              │
│   Docker Engine                 │
│   ┌──────────┐  ┌──────────┐   │
│   │ Traefik  │  │ App      │   │
│   │ (proxy)  │→ │ Container│   │
│   └──────────┘  └──────────┘   │
│   ┌──────────┐  ┌──────────┐   │
│   │ DB       │  │ Redis    │   │
│   │ Container│  │ Container│   │
│   └──────────┘  └──────────┘   │
└─────────────────────────────────┘
  • Control Plane — Runs the Coolify dashboard, API and build workers. Can be on the same server as your apps (single-server) or separate (multi-server).
  • Docker Engine — Coolify uses Docker to build images (via Nixpacks or Dockerfile) and run containers.
  • Traefik / Caddy — Reverse proxy that handles HTTP/HTTPS routing, load balancing and automatic TLS certificate renewal.
  • SSH — Coolify connects to remote servers over SSH to deploy containers, manage volumes and check health.

4. System Requirements

  • OS: Ubuntu 22.04+ / Debian 12+ (recommended). Other Linux distros with Docker support also work.
  • RAM: Minimum 2 GB (Coolify itself). 4 GB+ recommended for running apps alongside.
  • Disk: 30 GB+ SSD. Docker images and builds consume space quickly.
  • Network: Public IP, ports 80 and 443 open. SSH access (port 22).
  • Docker: Installed automatically by the Coolify install script if missing.

5. Installation

5.1 One-line install (recommended)

# SSH into your server as root
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

This script installs Docker (if needed), pulls the Coolify Docker images, creates volumes and starts the control plane. After ~2 minutes you'll see a URL to access the dashboard.

5.2 Post-install setup

  1. Open http://YOUR_IP:8000 in your browser.
  2. Create an admin account (email + password).
  3. Add your first server (localhost for single-server, or a remote IP).
  4. Coolify connects via SSH and validates Docker is running.
  5. You're ready to deploy!

5.3 Updating Coolify

# From the Coolify dashboard: Settings → Update → "Update Now"
# Or via CLI:
cd /data/coolify
docker compose pull
docker compose up -d

6. Dashboard Walkthrough

The Coolify UI is organized around these key sections:

  • Projects — Create projects, add environments (staging, production), and group resources.
  • Servers — Add, validate and monitor connected servers.
  • Resources — Deploy applications, databases and services within an environment.
  • Deployments — View build logs, rollback to previous deployments.
  • Settings — Configure SMTP, GitHub/GitLab apps, update Coolify.

7. Deploy Your First App

7.1 From a public GitHub repo

  1. Go to your project → environment → New Resource → Application.
  2. Select Public Repository and paste the URL (e.g., https://github.com/user/app).
  3. Choose Build Pack: Nixpacks (auto-detects language) or Dockerfile.
  4. Set the branch and build directory.
  5. Click Deploy. Coolify clones, builds and starts the container.

7.2 From a Dockerfile

# Example Dockerfile for a Node.js app
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Select "Dockerfile" as the build pack in Coolify. It will use your Dockerfile automatically.

7.3 Verifying the deployment

# Check running containers on your server
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# View logs for a specific container
docker logs -f coolify-app-xxxxx

8. Git Integration & Auto-Deploy

Coolify supports GitHub, GitLab, Bitbucket and Gitea. For private repos you create a GitHub/GitLab App or add a deploy key.

Auto-deploy workflow

  1. Connect your Git provider under Settings → Git Providers.
  2. When creating an application, select the private repository and branch.
  3. Enable Auto Deploy — Coolify registers a webhook in your repo.
  4. Every push to the configured branch triggers a build + deploy automatically.

You can also configure Preview Deployments: Coolify builds pull requests into temporary environments with unique URLs for review.

9. Managing Databases & Services

Coolify offers one-click deployment for common databases and services:

  • PostgreSQL — Production-ready with configurable versions and persistent volumes.
  • MySQL / MariaDB — Same one-click setup.
  • MongoDB — Document database with persistent storage.
  • Redis — In-memory cache/broker.
  • MinIO — S3-compatible object storage.
  • Custom — Any Docker image can be deployed as a service.

Coolify automatically generates connection strings and injects them as environment variables into your apps.

10. Custom Domains & TLS

  1. In your app settings, add a domain (e.g., app.example.com).
  2. Point the DNS record to your server's IP (A record or CNAME).
  3. Coolify's Traefik proxy automatically requests a Let's Encrypt certificate.
  4. HTTPS is enabled within seconds — auto-renewal is handled by Traefik.

For wildcard certificates, configure a DNS challenge provider (Cloudflare, etc.) in Traefik settings.

11. Environment Variables & Secrets

  • Set per-environment variables in the app settings (build-time and runtime).
  • Mark variables as secret — they are encrypted at rest.
  • Shared variables — Define variables at the project level and inherit them in all environments.
  • Database connection strings are auto-generated and injected.

12. Docker Compose Deployments

For multi-container stacks, use the Docker Compose build pack:

# docker-compose.yml example
version: "3.8"
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: ${DATABASE_URL}
    depends_on:
      - db
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

volumes:
  pgdata:

Coolify parses the Compose file, builds images, and manages the lifecycle of all services together.

13. Static Sites & Nixpacks

Nixpacks is Coolify's default build system. It auto-detects your language/framework (Node, Python, Go, Rust, Ruby, PHP, etc.) and generates a Docker image without needing a Dockerfile.

For static sites: set the build command (e.g., npm run build), the publish directory (e.g., dist), and Coolify serves it through Nginx or Caddy inside a container.

14. Backup & Restore

  • Database backups — Coolify can schedule automatic backups to S3-compatible storage (AWS S3, MinIO, Backblaze B2).
  • Frequency — Configure per-database: hourly, daily, weekly.
  • Restore — Download a backup from S3 and restore manually, or use the Coolify UI for one-click restore.
  • Coolify itself — Back up /data/coolify (contains the SQLite/PostgreSQL database, SSH keys and configuration).
# Manual backup of Coolify data directory
tar czf coolify-backup-$(date +%F).tar.gz /data/coolify

15. Monitoring & Logging

  • Built-in logs — Build logs and runtime logs available in the dashboard.
  • Docker Logs — docker logs -f <container> for real-time debugging.
  • Metrics — Integrate Prometheus + Grafana for CPU, memory and request metrics. Export Docker stats to Prometheus with cAdvisor.
  • Alerts — Configure Coolify notifications to Discord, Slack, Telegram or email for deployment failures or health check issues.

16. CI/CD Pipelines

Coolify acts as a CI/CD system on its own (Git push → build → deploy). For more complex pipelines:

  • GitHub Actions + Coolify API — Run tests in CI, then trigger a Coolify deploy via API/webhook on success.
  • GitLab CI — Same approach: build and test in GitLab, deploy with a Coolify webhook.
  • Rollbacks — The Coolify dashboard shows deployment history. Click any previous deployment to rollback instantly.
# GitHub Actions step to trigger Coolify deploy
- name: Deploy to Coolify
  run: |
    curl -X POST "https://coolify.example.com/api/v1/deploy" \
      -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"uuid": "app-uuid-here"}'

17. Multi-Server & Scaling

Coolify can manage multiple servers from one dashboard:

  1. Add a new server under Servers → New.
  2. Provide the IP and SSH key. Coolify validates Docker is installed.
  3. Deploy different apps/services to different servers.

For horizontal scaling of a single app, run multiple replicas behind Traefik's load balancer, or use Docker Swarm mode for more advanced orchestration.

18. Security Hardening

  • SSH key-only auth — Disable password login on your servers.
  • Firewall — UFW/iptables to expose only ports 22, 80, 443. Block the Coolify dashboard port (8000) from public access or put it behind Traefik with authentication.
  • Admin authentication — Use strong passwords. Consider adding Cloudflare Access or an auth proxy in front of the dashboard.
  • Docker security — Run containers as non-root where possible. Use read-only file systems.
  • Keep updated — Regularly update Coolify, Docker and the host OS.
  • Secrets encryption — Coolify encrypts secrets at rest. Never commit secrets to Git.
  • Network isolation — Place databases on internal Docker networks not exposed to the host.

19. Webhooks & API

Coolify exposes a REST API for programmatic management:

# List all applications
curl -s "https://coolify.example.com/api/v1/applications" \
  -H "Authorization: Bearer YOUR_API_TOKEN" | jq '.[]'

# Trigger deploy
curl -X POST "https://coolify.example.com/api/v1/applications/UUID/deploy" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Restart an application
curl -X POST "https://coolify.example.com/api/v1/applications/UUID/restart" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Webhooks for Git providers are configured automatically when you enable auto-deploy.

20. Troubleshooting

  • Build fails — Check build logs in the dashboard. Common issues: missing build command, wrong base image, port mismatch.
  • App not reachable — Verify DNS, check Traefik logs (docker logs coolify-proxy), ensure ports 80/443 are open.
  • TLS not working — DNS must propagate before Let's Encrypt can verify. Check Traefik ACME logs.
  • SSH connection failed — Verify the SSH key in Coolify matches the server's authorized_keys; check the server IP and port.
  • Out of disk — Docker images accumulate. Prune with docker system prune -a.
  • Container restarts — Check docker logs for OOM kills or crash loops. Increase memory limits if needed.

21. Coolify vs. Alternatives

  • Coolify vs. Heroku — Coolify is free and self-hosted; Heroku is managed but costs per dyno. Coolify gives you full server access.
  • Coolify vs. Vercel/Netlify — Vercel excels at serverless/edge; Coolify handles full-stack apps, databases and Docker on your own server.
  • Coolify vs. CapRover — Both are self-hosted PaaS. Coolify has a more modern UI, Nixpacks support and multi-server management. CapRover uses Captain Definition files.
  • Coolify vs. Dokku — Dokku is CLI-only and single-server. Coolify has a web UI and multi-server support.
  • Coolify vs. Kubernetes — Kubernetes is for large-scale orchestration. Coolify is simpler for small-to-medium workloads where K8s is overkill.

22. Real-World Use Cases

  1. Indie hackers / side projects — Deploy multiple SaaS apps on a single $10/mo VPS.
  2. Agencies — Host client projects with isolated environments and custom domains.
  3. Startups — Replace Heroku for predictable costs while keeping easy Git-push deploys.
  4. Internal tools — Deploy dashboards, admin panels and APIs on-premises.
  5. Education — Give students their own environments to deploy projects.

23. Production Readiness Checklist

  • ☐ Server firewall configured (only 22, 80, 443 open)
  • ☐ SSH key-only authentication enabled
  • ☐ Coolify dashboard behind auth proxy or VPN
  • ☐ Automatic database backups to S3 configured
  • ☐ Coolify data directory (/data/coolify) backed up
  • ☐ Monitoring and alerts (Discord/Slack/email) configured
  • ☐ Custom domains + TLS verified and working
  • ☐ Environment variables marked as secrets where appropriate
  • ☐ Docker prune cron job set up to prevent disk exhaustion
  • ☐ Resource limits (CPU/memory) set for each container
  • ☐ Rollback tested — can you redeploy a previous version?
  • ☐ OS and Docker auto-updates or scheduled maintenance plan

24. FAQ

Is Coolify free?

Yes. Coolify is open-source (AGPLv3). You can self-host it for free. There is also a paid cloud version where the team manages the infrastructure for you.

What languages/frameworks does Coolify support?

Any language that can run in Docker. Nixpacks auto-detects Node.js, Python, Go, Rust, Ruby, PHP, Java, .NET and more. You can also use your own Dockerfile or Docker Compose.

Can I run Coolify on a $5 VPS?

Coolify itself needs ~512 MB RAM. On a 1 GB VPS you can run Coolify + 1 small app. For comfortable usage with databases, 4 GB+ is recommended.

How does Coolify handle zero-downtime deployments?

Coolify starts the new container, waits for the health check to pass, then switches Traefik routing and stops the old container. This gives you near-zero-downtime deployments out of the box.

Can I use Coolify with an existing Docker setup?

Yes. Coolify manages its own containers but doesn't interfere with other containers on the same server, as long as there are no port conflicts.

Is Coolify production-ready?

Many teams and indie hackers use Coolify in production. However, you are responsible for backups, security and monitoring — the same as any self-hosted solution.

25. Glossary

PaaS
Platform as a Service — a cloud model where the provider manages infrastructure and you deploy applications.
Nixpacks
An open-source build system that auto-detects your app's language and creates a Docker image without a Dockerfile.
Traefik
A modern reverse proxy and load balancer designed for containerized environments. Handles automatic TLS via Let's Encrypt.
Let's Encrypt
A free, automated certificate authority that provides TLS/SSL certificates.
Docker Compose
A tool for defining and running multi-container Docker applications using a YAML file.
Webhook
An HTTP callback triggered by an event (e.g., Git push) that notifies another service to take action.
Health Check
A periodic probe that verifies a container or service is running correctly.
Rollback
Reverting to a previous deployment version when the current one fails.
Build Pack
A strategy for building an application into a Docker image — Nixpacks, Dockerfile or Compose.

26. References & Further Reading

27. Conclusion

Coolify brings the ease of cloud PaaS to your own server. It is an excellent choice for indie hackers, small teams and agencies that want full control, predictable costs and a modern deployment experience without the complexity of Kubernetes or the bills of managed cloud services.

Start with a single VPS, deploy one app, and expand from there. The combination of Git auto-deploy, one-click databases, automatic TLS and a clean dashboard makes Coolify one of the best self-hosted deployment tools available today.

Spin up a $10 VPS, run the one-line install, and deploy your first app in under 10 minutes. You'll never go back to pushing via FTP.