Coolify Self-Hosted PaaS Installation

Coolify is a self-hosted Heroku and Netlify alternative that lets you deploy applications, databases, and services on your own VPS or baremetal server using Docker. With Git integration, SSL automation, and a clean web UI, Coolify provides full PaaS functionality without vendor lock-in or per-seat pricing.

Prerequisites

  • A VPS with at least 2 CPU cores and 2 GB RAM (4 GB recommended)
  • Ubuntu 20.04+ or Debian 11+ (fresh install recommended)
  • A domain name pointed to your server's IP
  • Root or sudo access
  • Ports 80, 443, and 8000 open in your firewall

Installing Coolify

Coolify provides a one-line installer that sets up Docker, Docker Compose, and all required services:

# Run the official installer as root
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# The installer will:
# 1. Install Docker and Docker Compose
# 2. Pull Coolify images
# 3. Start the Coolify stack
# 4. Display the access URL

# Check installation status
docker ps | grep coolify

# View installer logs if something fails
journalctl -u docker -f

After installation, Coolify runs on port 8000 by default. Access it at http://your-server-ip:8000.

Firewall Configuration

# Ubuntu/Debian with UFW
sudo ufw allow 22/tcp      # SSH
sudo ufw allow 80/tcp      # HTTP
sudo ufw allow 443/tcp     # HTTPS
sudo ufw allow 8000/tcp    # Coolify dashboard
sudo ufw enable

# CentOS/Rocky with firewalld
sudo firewall-cmd --permanent --add-port=22/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

Initial Setup and Dashboard

  1. Open http://your-server-ip:8000 in your browser
  2. Create your admin account on first launch
  3. Set your instance URL (used for webhooks and OAuth callbacks)
  4. Configure your email settings for notifications
# View Coolify configuration
cat /data/coolify/source/.env

# Restart Coolify stack if needed
cd /data/coolify/source
docker compose pull
docker compose up -d

# Check logs
docker logs coolify --tail 100 -f

Connecting a Server

Coolify can manage multiple servers via SSH. The server running Coolify itself is auto-added as "localhost."

Adding a remote server:

  1. Go to Servers in the dashboard
  2. Click Add Server
  3. Enter server IP, SSH user, and port
  4. Paste your SSH private key (generate one if needed)
# Generate SSH key for Coolify to use
ssh-keygen -t ed25519 -f ~/.ssh/coolify -N ""

# Display public key to add to remote server
cat ~/.ssh/coolify.pub

# Add public key to remote server
ssh-copy-id -i ~/.ssh/coolify.pub user@remote-server-ip

# Test SSH connection
ssh -i ~/.ssh/coolify user@remote-server-ip "echo Connected"

After adding the server, Coolify installs Docker on it automatically.

Git Integration and Application Deployment

Connecting GitHub/GitLab

  1. Go to Sources in the dashboard
  2. Add a GitHub App or GitLab OAuth application
  3. Install the GitHub App on your repositories
# For private GitHub repos, create a personal access token with:
# - repo (full control)
# - admin:repo_hook (for webhooks)

Deploying an Application

  1. Go to Projects → New Project
  2. Click Add Resource → Application
  3. Select your Git source and repository
  4. Choose a branch and deployment method

Coolify auto-detects buildpacks for common frameworks. For custom deployments, add a Dockerfile:

# Example Dockerfile for a Node.js app
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["node", "dist/server.js"]

Environment Variables

# Set in Coolify dashboard under Application → Environment Variables
# Or use a .env file in your repository (not recommended for secrets)

# Example variables commonly needed:
DATABASE_URL=postgresql://user:pass@db:5432/mydb
REDIS_URL=redis://redis:6379
SECRET_KEY=your-secret-key
NODE_ENV=production

Deploy on Push

Coolify supports automatic deployment via webhooks:

  1. Go to your application settings
  2. Enable Auto Deploy on Push
  3. Copy the webhook URL
  4. Add it to your GitHub/GitLab repository webhooks

Database Management

Coolify supports one-click database deployment:

  1. Go to your project → Add Resource → Database
  2. Choose from: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, etc.
  3. Set credentials and version
# Connect to a deployed PostgreSQL database
# Get the connection string from Coolify dashboard
psql "postgresql://user:password@server-ip:5432/dbname"

# Run database backup manually
docker exec coolify-postgres pg_dump -U user dbname > backup.sql

# Restore from backup
docker exec -i coolify-postgres psql -U user dbname < backup.sql

Scheduled Backups

  1. Go to your database resource in Coolify
  2. Click Backups → Enable Scheduled Backups
  3. Configure S3-compatible storage for remote backups

SSL Automation

Coolify uses Let's Encrypt via Traefik for automatic SSL:

  1. Go to Servers → your server → Proxy
  2. Ensure Traefik proxy is running
  3. Add your domain to the application's domain settings
# Verify Traefik is running
docker ps | grep traefik

# Check Traefik logs for certificate issues
docker logs coolify-proxy --tail 50

# Ensure your domain DNS is pointing to the server
dig +short yourdomain.com

# Test SSL after deployment
curl -I https://yourdomain.com

For wildcard certificates, configure DNS challenge:

# In Coolify dashboard: Servers → Proxy → Advanced
# Add Cloudflare API token for DNS-01 challenge
# This enables wildcard cert support: *.yourdomain.com

Team Collaboration

Coolify supports multi-user access with role-based permissions:

  1. Go to Settings → Members
  2. Invite team members by email
  3. Assign roles: Admin, Member, or Read-only
# Coolify also supports SSO via:
# - GitHub OAuth
# - GitLab OAuth
# Configure under Settings → Authentication

Project-level access control:

  • Create separate projects per team or client
  • Assign members to specific projects
  • Resources in different projects are isolated

Troubleshooting

Coolify dashboard not accessible:

# Check if containers are running
docker ps -a | grep coolify

# Restart Coolify
cd /data/coolify/source
docker compose restart

# Check system resources
free -h
df -h

Deployment fails with build error:

# View build logs in Coolify dashboard: Application → Deployments → [latest]
# Or check Docker logs
docker logs coolify-builder --tail 100

# Ensure Dockerfile is valid
docker build -t test . --no-cache

SSL certificate not issuing:

# Verify domain DNS propagation
nslookup yourdomain.com

# Check Let's Encrypt rate limits (max 5 certs per domain per week)
# Traefik logs show detailed ACME errors
docker logs coolify-proxy 2>&1 | grep -i acme

Database connection refused:

# Check database container is running
docker ps | grep coolify-db

# Verify network connectivity between app and db
docker network ls
docker network inspect coolify

Conclusion

Coolify delivers a complete self-hosted PaaS experience with Docker-powered deployments, automatic SSL, and multi-server management from a single dashboard. It eliminates per-seat cloud PaaS costs while giving you full control over your infrastructure. Start with a single VPS and scale to multiple servers as your application portfolio grows.