Coolify Setup: Application Deployment with Self-Hosted PaaS

Coolify Setup: Application Deployment with Self-Hosted PaaS

Coolify is an open-source, self-hosted alternative to cloud platforms like Heroku, Netlify, and Vercel. With Coolify running on your own server, you can easily manage your applications, databases, and services. This Docker-based platform supports automatic deployment when you push code via Git integration.

What is Coolify?

Coolify is a modern PaaS solution that lets you manage multiple servers and applications from a single interface. Key features:

• Automatic SSL: Free SSL certificates via Let's Encrypt
• Git Integration: GitHub, GitLab, Bitbucket support
• Multi-Server: Manage multiple servers from one panel
• Database Services: PostgreSQL, MySQL, Redis, MongoDB
• Docker Compose: Deploy existing compose files directly
• Webhooks: Automatic deployment triggers

System Requirements

• Ubuntu 20.04/22.04 or Debian 11/12
• Minimum 2 GB RAM (4 GB recommended)
• Minimum 30 GB disk space
• Docker should NOT be installed (Coolify installs its own Docker)

Installation

Coolify installation is done with a single curl command:

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

The installation script automatically:

• Installs Docker and Docker Compose
• Downloads and starts Coolify containers
• Configures required networks and volumes
• Sets firewall rules (port 8000)

After installation, access via browser:

http://SERVER_IP:8000

Initial Configuration

Creating Admin Account

On first login, set your email and password. These credentials are stored in the Coolify database.

Adding a Server

Coolify automatically adds the server it's installed on (localhost). To add additional servers:

1. Servers → Add Server
2. Enter SSH connection details (IP, port, username)
3. Add SSH private key
4. Test connection with Validate & Save

# Generate SSH key for Coolify to connect to remote servers
ssh-keygen -t ed25519 -C "coolify@myserver"
# Add public key to remote server
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-server

Adding Git Sources

GitHub Integration

1. Sources → Add Source → GitHub App
2. Create an OAuth App or GitHub App on GitHub
3. Enter Client ID and Client Secret
4. Callback URL: http://SERVER_IP:8000/auth/github

GitLab Integration

# Create a Personal Access Token on GitLab
# Required scopes: api, read_user, read_repository

1. Sources → Add Source → GitLab
2. Enter GitLab URL and Access Token
3. Test the connection

Deploying Applications

Creating a New Project

1. Projects → New Project
2. Enter project name and description
3. Select Environment (production, staging, etc.)

Adding an Application

1. Inside the project, New Resource → Application
2. Select Git source
3. Choose repository and branch
4. Select build pack:
   • Nixpacks: Auto-detection (Node.js, Python, PHP, Ruby, etc.)
   • Dockerfile: Use your own Dockerfile
   • Docker Compose: compose.yml file
   • Static: Static HTML/CSS/JS

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

Environment Variables

Go to the Environment Variables tab in application settings:

# Example environment variables
NODE_ENV=production
DATABASE_URL=postgresql://user:pass@db:5432/myapp
REDIS_URL=redis://redis:6379
SECRET_KEY=your-secret-key-here
PORT=3000

Domain and SSL Configuration

1. Domains tab in application settings
2. Enter domain name: app.example.com
3. Enable SSL option (Let's Encrypt automatic)
4. Create DNS A record: app.example.com → SERVER_IP

# Verify DNS record
nslookup app.example.com
dig app.example.com A

Database Services

PostgreSQL Setup

1. New Resource → Database → PostgreSQL
2. Select version (14, 15, 16)
3. Set username and password
4. Click Deploy

# Coolify PostgreSQL connection details
# Internal URL (for apps on the same server):
postgresql://coolify:password@postgres:5432/mydb

# External URL (for external access):
postgresql://coolify:password@SERVER_IP:PORT/mydb

Redis Setup

# New Resource → Database → Redis
# Version: 7.x
# Internal connection:
redis://default:password@redis:6379

Database Backups

Coolify offers automatic backup functionality:

1. Backups tab in database settings
2. Set backup frequency (daily, weekly)
3. Add S3-compatible storage (AWS S3, MinIO, Cloudflare R2)

# Manual backup
coolify backup create --database postgres-id

# List backups
coolify backup list

Deploy with Docker Compose

You can import existing docker-compose.yml files directly into Coolify:

# docker-compose.yml example
version: '3.8'
services:
  app:
    image: myapp:latest
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Automatic Deployment (Webhook)

Set up webhooks for automatic deployment after git push:

1. Webhooks tab in application settings
2. Copy the webhook URL
3. Add to GitHub/GitLab repository settings:

# GitHub Webhook settings:
# Payload URL: https://coolify.example.com/webhooks/github
# Content type: application/json
# Secret: Secret copied from Coolify
# Events: Push events

Updating Coolify

# Update Coolify to the latest version
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# Or from the web interface:
# Settings → Updates → Update Coolify

Troubleshooting

# View Coolify logs
docker logs coolify

# List all Coolify containers
docker ps | grep coolify

# Restart Coolify
docker restart coolify

# Proxy (Traefik) logs
docker logs coolify-proxy