# Coolify Self-hosted PaaS

> Open-source Heroku/Netlify alternative for deploying applications.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: coolify, postgresql, redis
- Tags: paas, deployment, coolify, heroku-alternative, self-hosted
- Source: https://docker.recipes/devops/coolify-paas

## Overview

Coolify is an open-source, self-hosted Platform-as-a-Service (PaaS) that provides an alternative to cloud services like Heroku, Netlify, and Vercel. Developed by Coollabs, it enables developers and organizations to deploy applications, databases, and services on their own infrastructure while maintaining the simplicity of modern PaaS offerings. Coolify supports multiple deployment methods including Git repositories, Docker images, and static sites, with built-in SSL management, monitoring, and scaling capabilities. This deployment creates a complete Coolify instance using three essential services: the main Coolify application server, a PostgreSQL database for storing application metadata and configurations, and Redis for caching and real-time features. The Coolify container handles the web interface, API, and deployment orchestration, while PostgreSQL maintains persistent data about projects, deployments, and user configurations. Redis provides session management, job queuing, and WebSocket support for real-time updates in the dashboard. This stack is ideal for development teams seeking complete control over their deployment pipeline, organizations with compliance requirements that prevent cloud PaaS usage, and infrastructure engineers building internal developer platforms. The combination provides enterprise-grade deployment capabilities while remaining cost-effective compared to managed PaaS solutions, especially for teams managing multiple applications and environments.

## Features

- Multi-application deployment supporting Node.js, Python, PHP, Go, Rust, and static sites
- Git-based continuous deployment with webhook integration for GitHub, GitLab, and Bitbucket
- Built-in database provisioning for PostgreSQL, MySQL, MongoDB, and Redis instances
- Automatic SSL certificate management with Let's Encrypt integration
- Real-time deployment logs and application monitoring through WebSocket connections
- Docker Compose and Dockerfile support for complex multi-container applications
- Environment variable management with per-branch configuration support
- Team collaboration features with role-based access control and project sharing

## Use cases

- Development teams replacing Heroku due to pricing changes or feature limitations
- Enterprises requiring on-premises application deployment for compliance or security
- Startups building multiple microservices needing centralized deployment management
- Educational institutions providing students with self-hosted development platforms
- DevOps teams creating internal developer platforms for streamlined CI/CD
- Agencies managing client applications on dedicated infrastructure
- Open-source projects requiring free, scalable hosting without vendor lock-in

## Prerequisites

- Minimum 2GB RAM and 10GB disk space for the complete stack
- Docker and Docker Compose installed on the host system
- Access to port 8000 for the web interface and ports 6001-6002 for WebSocket connections
- Domain name and DNS configuration for SSL certificate generation (optional but recommended)
- Understanding of Git workflows and Docker concepts for application deployment
- SSH access to target deployment servers if deploying to remote infrastructure

## docker-compose.yml

```yaml
services:
  coolify:
    image: ghcr.io/coollabsio/coolify:latest
    container_name: coolify
    environment:
      - APP_ID=${APP_ID}
      - APP_KEY=${APP_KEY}
      - APP_NAME=Coolify
      - DB_USERNAME=coolify
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - PUSHER_APP_ID=${PUSHER_APP_ID}
      - PUSHER_APP_KEY=${PUSHER_APP_KEY}
      - PUSHER_APP_SECRET=${PUSHER_APP_SECRET}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - coolify-data:/data/coolify
    ports:
      - "8000:80"
      - "6001:6001"
      - "6002:6002"
    depends_on:
      - db
      - redis
    networks:
      - coolify-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: coolify-db
    environment:
      - POSTGRES_USER=coolify
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=coolify
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - coolify-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: coolify-redis
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis-data:/data
    networks:
      - coolify-network
    restart: unless-stopped

volumes:
  coolify-data:
  postgres-data:
  redis-data:

networks:
  coolify-network:
    driver: bridge
```

## .env

```bash
# Coolify
DB_PASSWORD=secure_coolify_password
REDIS_PASSWORD=secure_redis_password

# Generate with: openssl rand -hex 16
APP_ID=random_app_id

# Generate with: openssl rand -base64 32
APP_KEY=base64:your_app_key

# Pusher (for real-time updates)
PUSHER_APP_ID=coolify
PUSHER_APP_KEY=coolify
PUSHER_APP_SECRET=coolify_secret
```

## Usage notes

- Web UI at http://localhost:8000
- Register first admin account
- Deploy apps from Git repos
- Supports Docker, static sites, databases
- Auto SSL with Let's Encrypt

## Troubleshooting

- Coolify container fails to start with permission errors: Ensure Docker socket has proper permissions with 'sudo chmod 666 /var/run/docker.sock'
- Database connection failed during initial setup: Verify DB_PASSWORD environment variable matches between coolify and db services
- Redis authentication errors in application logs: Check REDIS_PASSWORD is set and consistent across services
- SSL certificate generation fails: Verify domain DNS points to server and port 80/443 are accessible from internet
- Git webhook deployments not triggering: Confirm PUSHER_* environment variables are configured and ports 6001-6002 are accessible
- Out of disk space errors during deployment: Monitor Docker volumes and implement log rotation for coolify-data volume

