Deploy with Coolify: The Complete Guide to Self-Hosting Any App on Your VPS

Why Self-Host with Coolify?

Cloud platforms are convenient right up until the moment they're not. Heroku killed its free tier. Railway's pricing scaled with your traffic. Render's cold starts punished your users. If you've been burned by any of these, Coolify is worth your attention.

Coolify is an open-source, self-hosted Platform as a Service (PaaS). You run it on your own VPS. It handles Docker containers, Git deployments, SSL certificates, reverse proxying, databases, cron jobs, and more — all through a clean dashboard. Think Heroku, but you own the server.

The tradeoff is real: you're responsible for the machine. But for teams and solo developers who want control, predictable costs, and zero vendor lock-in, that tradeoff is completely worth it.

This guide walks you through the full setup — from spinning up a VPS to deploying your first production app with automatic HTTPS.

Already running Coolify and want to go deeper? Check out our guide on Git deployments, databases, multi-server management, and production CI/CD.

Prerequisites

Before you start, make sure you have the following in place:

• A VPS with root or sudo access — Hetzner, DigitalOcean, Vultr, Linode, or any provider works. Hetzner CPX21 (3 vCPU, 4 GB RAM) is a popular starting point.
• OS: Ubuntu 22.04 LTS or 24.04 LTS (recommended). Debian, AlmaLinux, Rocky Linux, and Arch also work. Non-LTS Ubuntu versions require manual installation.
• Minimum specs: 2 CPU cores, 2 GB RAM, 30 GB storage. For running build processes alongside workloads, 4 GB RAM is safer.
• A domain name with DNS managed by Cloudflare, your registrar, or any provider — you'll need to point an A record at your server IP.
• SSH key pair — password auth is fine for initial setup but key-based auth should be configured before hardening.
• Basic Linux familiarity — you should be comfortable running commands over SSH.

Step 1: Prepare Your VPS

SSH into your server and run a full package update first. Never skip this on a fresh VPS.

ssh root@YOUR_SERVER_IP
apt update && apt upgrade -y
apt install -y curl wget git ufw

Then configure your firewall. Coolify needs a specific set of ports open. Lock down everything else:

# Allow SSH — do this FIRST or you'll lock yourself out
ufw allow 22/tcp

# HTTP and HTTPS for your deployed apps
ufw allow 80/tcp
ufw allow 443/tcp

# Coolify dashboard
ufw allow 8000/tcp

# Coolify real-time terminal (needed for live logs in the dashboard)
ufw allow 6001/tcp
ufw allow 6002/tcp

# Enable firewall
ufw --force enable
ufw status

Important: Port 8000 is the Coolify web UI. Once you've set up a custom domain for the dashboard, you can close this port and access it only through your domain on 443.

Step 2: Install Coolify

Coolify provides a one-line install script that handles Docker, Docker Compose, and the full Coolify stack automatically.

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

The installer will:

• Install Docker and Docker Compose if not already present
• Pull the Coolify image and all supporting services
• Configure Traefik as the reverse proxy
• Start everything as a set of Docker containers

Once complete, the installer prints your dashboard URL. It'll look like this:

Coolify is ready!
Dashboard URL: http://YOUR_SERVER_IP:8000

Open that URL in your browser and complete the initial setup wizard. You'll create your admin account and configure your first server (which will be the machine you just installed on — a "localhost" server in Coolify's terminology).

Manual Installation (Non-LTS Ubuntu / Advanced)

If you're on a non-LTS Ubuntu release or want more control, install Docker manually first:

# Install Docker Engine
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (if not running as root)
usermod -aG docker $USER

# Then run the Coolify installer
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Step 3: Connect a Git Source and Deploy Your First App

This is where Coolify earns its keep. Once you're logged into the dashboard, you can connect a GitHub, GitLab, Gitea, or Bitbucket account and deploy from any repository in a few clicks.

Connect GitHub

1. Go to Sources in the left sidebar
2. Click Add GitHub App
3. Follow the OAuth flow — Coolify installs a GitHub App on your account or org
4. Select which repos to grant access to

This gives Coolify a webhook endpoint so GitHub pushes automatically trigger new deployments.

Create a New Application

1. Go to Projects → New Project
2. Inside the project, click New Resource → Application
3. Choose your GitHub source and pick the repo and branch
4. Coolify auto-detects your build method (Nixpacks for most Node.js/Python/Ruby/Go apps, Dockerfile if you have one, or Docker Compose)
5. Set your domain (e.g., app.yourdomain.com)
6. Hit Deploy

Coolify builds your container, starts it, and routes traffic through Traefik. If your domain is pointed at the server, HTTPS via Let's Encrypt is provisioned automatically — no Certbot commands needed.

Environment Variables

Set environment variables under the Environment Variables tab of your application. You can switch between a form view (Normal View) and raw key=value pairs (Developer View):

# Example .env values you'd paste in Developer View
NODE_ENV=production
DATABASE_URL=postgresql://user:password@postgres:5432/mydb
REDIS_URL=redis://redis:6379
JWT_SECRET=your-super-secret-key-here
PORT=3000

Secrets are stored encrypted in Coolify's database and injected at deploy time. They are never written to your source repository.

Step 4: Add Databases and Persistent Storage

Coolify has first-class support for deploying databases alongside your apps. PostgreSQL, MySQL, MariaDB, MongoDB, Redis, and KeyDB are all one-click installs from the New Resource → Database menu.

Deploy a PostgreSQL Database

1. In your project, click New Resource → Database → PostgreSQL
2. Set a database name, username, and password
3. Choose a version (defaults to latest stable)
4. Click Start

Coolify connects your database to the same internal Docker network as your app. Reference it by the container service name — no external hostname needed for internal traffic.

# Internal connection string when your app and DB are in the same Coolify project
DATABASE_URL=postgresql://myuser:mypassword@your-db-uuid:5432/mydb

# The hostname is the internal service name shown in the Coolify DB detail page
# It resolves over Docker's internal network — no public exposure needed

Persistent Volumes

For stateful apps, attach a persistent volume so data survives redeployments. Under your app's Storages tab, add a volume mount:

# Example: persisting an app's upload directory
# Source path (on the VPS host)
/data/coolify/volumes/myapp-uploads

# Target path (inside the container)
/app/uploads

Coolify creates a Docker bind mount at the source path. Back this directory up regularly if it contains critical data — Coolify does not manage backups for you by default.

Step 5: Configure SSL and Custom Domains

Coolify uses Traefik as its reverse proxy and Let's Encrypt for SSL. Once your DNS A record points to your server IP, HTTPS provisioning is fully automatic.

Add a Custom Domain to Your App

1. Open your application in the dashboard
2. Go to the General tab
3. Set the FQDN field to your domain (e.g., https://app.yourdomain.com)
4. Redeploy

Traefik watches for the new routing rule and requests the cert from Let's Encrypt within minutes. No manual Nginx or Certbot config required.

Force HTTPS Redirect

Traefik enforces HTTPS by default for all Coolify-managed apps. If you need to confirm or customize it, the proxy config lives at:

# Coolify Traefik config directory on the VPS
ls /data/coolify/proxy/

# Dynamic config directory (auto-managed by Coolify)
ls /data/coolify/proxy/dynamic/

# You can inspect the generated Traefik config here — avoid editing directly,
# use Coolify's UI proxy settings instead to prevent config drift

For advanced Traefik customization (Cloudflare DNS challenge, wildcard certs, custom middleware), see the Coolify production CI/CD and multi-server guide on sysbrix.com.

Step 6: Set Up Automatic Git Deployments and CI/CD

Coolify auto-deploys on every push to the branch you configured — no external CI service needed for simple pipelines.

How Webhooks Work

When you connect a GitHub App source, Coolify registers a webhook on your repo. Every push to the watched branch sends a payload to Coolify's webhook endpoint, which triggers a fresh build and rolling deployment.

You can also grab the manual deploy webhook URL from your app's General tab and trigger it from any external CI system:

# Trigger a deploy from GitHub Actions (or any CI)
curl -X GET \
  -H "Authorization: Bearer YOUR_COOLIFY_WEBHOOK_TOKEN" \
  "https://coolify.yourdomain.com/api/v1/deploy?uuid=YOUR_APP_UUID&force=false"

Preview Deployments for Pull Requests

Enable preview deployments under your app's General → Preview Deployments toggle. When a PR is opened against your watched branch, Coolify automatically spins up an isolated deployment at a generated subdomain. It tears it down when the PR closes.

This is a huge quality-of-life feature for teams — no separate Vercel or Netlify account needed for previews.

For teams running complex queue-based workloads on Coolify, also see our deep-dive on n8n Coolify deployment with queue mode, worker scaling, and production hardening.

Step 7: Production Hardening

A default Coolify install is functional but not fully hardened. Run through this checklist before you go live.

Secure SSH Access

# Disable password auth and root login in SSH config
sudo nano /etc/ssh/sshd_config

# Set these values:
# PasswordAuthentication no
# PermitRootLogin prohibit-password
# PubkeyAuthentication yes

# Restart SSH
sudo systemctl restart sshd

Keep Docker and Coolify Updated

# Update Coolify from the dashboard:
# Settings → General → Update Coolify

# Or via CLI (Coolify manages its own containers):
cd /data/coolify
docker compose pull
docker compose up -d --remove-orphans

Additional Hardening Checklist

• Restrict dashboard access — Consider putting the Coolify UI (port 8000/443) behind an IP allowlist or VPN rather than leaving it publicly accessible.
• Enable 2FA — Coolify supports TOTP-based two-factor authentication. Enable it under your profile settings immediately after setup.
• Rotate secrets regularly — Use Coolify's encrypted environment variables, never hardcode secrets in your repo.
• Set resource limits — Add CPU and memory limits to containers from the Advanced tab to prevent any single app from starving your VPS.
• Set up automated backups — Use a VPS provider snapshot schedule or a tool like Restic to back up /data/coolify and your database volumes regularly.
• Monitor your server — Coolify includes basic real-time resource stats in the dashboard, but consider adding Grafana + Prometheus or Netdata for deeper visibility.

Tips and Troubleshooting

Deployment stuck at "Building"

Open the Logs tab on your deployment. The build output is streamed live. Common causes: missing environment variable, Nixpacks couldn't detect the runtime (add a nixpacks.toml to guide it), or the container crashed on startup. Always read the logs before opening a support thread.

SSL certificate not provisioning

Check that your DNS A record has propagated and points to the correct server IP (dig A app.yourdomain.com). Traefik can't request a cert if the domain doesn't resolve to the server. Also check that port 80 is open — Let's Encrypt's HTTP-01 challenge requires it.

App is running but not reachable

Verify the container is actually listening on the port Coolify expects. Set the correct Port value in your app's General settings — it must match the port your process binds to inside the container (check your Dockerfile EXPOSE directive or your app's config).

Database connection refused

Make sure your app and database are in the same Coolify project. The internal Docker hostname shown in the database detail page is only resolvable from containers on the same Docker network. If your app is in a different project, you'll need to expose the DB port externally — which you should only do with a strong password and ideally an IP allowlist.

Dashboard shows server as unreachable

Coolify communicates with servers over SSH. If you changed SSH port or key, go to Servers → [Your Server] → Configuration and update the SSH settings. Run the Validate & Configure button to test connectivity.

Container keeps restarting

Run docker ps on the VPS to see the container's restart count. Then tail the container logs directly:

# List running Coolify-managed containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Tail logs for a specific container
docker logs --tail 100 -f your-container-name

# Check resource usage
docker stats --no-stream

Nixpacks build fails for a monorepo

Set the Base Directory in your app's General settings to point at the subfolder containing your application code. Nixpacks will then run from that directory instead of the repo root.

What to Do Next

You now have a working self-hosted PaaS on your own VPS. Here's where to go from here:

• Add more servers — Coolify supports multi-server management from a single dashboard. Spin up remote servers for production workloads and keep your Coolify control plane separate. See our multi-server and CI/CD deep-dive for the full setup.
• Deploy automation tools — Self-hosting n8n, Windmill, or Temporal on Coolify gives you powerful workflow automation at zero per-execution cost. Our n8n queue mode and worker scaling guide walks through a production-grade setup.
• Explore the one-click app library — Coolify ships with a growing library of pre-configured services (Plausible, Umami, Ghost, Gitea, Supabase, and more) that deploy in minutes.
• Set up team access — Invite collaborators from Settings → Users. Role-based access control is available on the Pro tier.

And if you're just getting started with Coolify in general, our beginner-friendly overview — The Self-Hoster's Guide to Running Any App on Your Own VPS — covers the concepts before you dive into the technical details.

Need Enterprise-Grade Help?

Self-hosting is powerful, but some teams need more than a dashboard and a VPS. If you're looking for managed infrastructure, custom Coolify configurations, high-availability setups, or hands-on DevOps support, Sysbrix can help.

Talk to our team → We work with teams of all sizes to get self-hosted infrastructure running at scale — reliably, securely, and without the headaches.