title: "Deploy on Coolify"
description: "Deploy OpenCodeHub on Coolify, the self-hosted PaaS alternative to Heroku and Render"

Difficulty: Easy | Time: 20 minutes | Method: Docker Compose (Git-based)

Coolify is an open-source, self-hosted alternative to Heroku, Netlify, and Render. It makes deploying OpenCodeHub incredibly simple with built-in SSL, automatic deployments, and managed databases.

Prerequisites

• A server (VPS) with Ubuntu 22.04/24.04, Debian 12, or CentOS 9
• Minimum 2 CPU cores, 4GB RAM, 40GB SSD
• A domain name pointed to your server (e.g., git.yourdomain.com)
• Coolify v4 installed on your server

Step 1: Install Coolify

If you haven't installed Coolify yet, run this on your server:

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

After installation:

1. Open http://your-server-ip:8000
2. Complete the onboarding wizard
3. Set up your domain (e.g., coolify.yourdomain.com)

Step 2: Create Resources in Coolify

2.1 Create a Project

1. In Coolify dashboard, click Projects → Add
2. Name it OpenCodeHub
3. Select your server and environment (e.g., production)

2.2 Create a PostgreSQL Database

1. Go to your project → Resources → Add New Resource → Database
2. Select PostgreSQL
3. Configuration:

   Name: opencodehub-postgres
   Version: 16
   Database: opencodehub
   Username: opencodehub
   Password: <generate-strong-password>
   

4. Click Start
5. Note down the internal connection string (e.g., postgresql://opencodehub:password@opencodehub-postgres:5432/opencodehub)

2.3 Create a Redis Instance

1. Add New Resource → Database → Redis
2. Configuration:

   Name: opencodehub-redis
   Version: 7-alpine
   Password: <generate-strong-password>
   

3. Click Start
4. Note down the internal URL (e.g., redis://:password@opencodehub-redis:6379)

Step 3: Deploy OpenCodeHub Application

3.1 Add the Git Repository

1. Go to your project → Resources → Add New Resource → Application
2. Select Public Repository
3. Repository URL: https://github.com/swadhinbiswas/OpencodeHub.git
4. Branch: main
5. Build Pack: Docker Compose
6. Click Continue

3.2 Configure the Docker Compose

Coolify will auto-detect the docker-compose.yml. You need to customize it for Coolify's environment:

Replace the detected compose with this Coolify-optimized version:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: opencodehub
    restart: unless-stopped
    ports:
      - "4321:4321"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
      - SESSION_SECRET=${SESSION_SECRET}
      - INTERNAL_HOOK_SECRET=${INTERNAL_HOOK_SECRET}
      - CRON_SECRET=${CRON_SECRET}
      - RUNNER_SECRET=${RUNNER_SECRET}
      - WORKFLOW_SECRET_ENCRYPTION_KEY=${WORKFLOW_SECRET_ENCRYPTION_KEY}
      - SITE_URL=${COOLIFY_FQDN:-http://localhost:4321}
      - SSH_HOST_KEY_PATH=/data/ssh/host_key
      - STORAGE_TYPE=local
      - STORAGE_PATH=/data/storage
      - REPOS_PATH=/data/repos
    volumes:
      - opencodehub-repos:/data/repos
      - opencodehub-storage:/data/storage
      - opencodehub-ssh:/data/ssh
      - opencodehub-cache:/data/cache
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4321/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  opencodehub-repos:
  opencodehub-storage:
  opencodehub-ssh:
  opencodehub-cache:

3.3 Set Environment Variables

In Coolify, go to your app → Environment Variables and add:

Security Tip: Use Coolify's "Secret" toggle for all *_SECRET variables so they are encrypted at rest.

3.4 Configure Persistent Storage

In your app settings → Persistent Storage, verify these volumes are created:

Step 4: Configure Domain & SSL

4.1 Set Domain

1. In your app → Settings → Domains
2. Add your domain: git.yourdomain.com
3. Coolify will automatically configure the reverse proxy

4.2 Enable SSL

1. Go to Settings → SSL/TLS
2. Select Let's Encrypt (Auto)
3. Enable HTTPS Redirect
4. Click Save

Coolify handles:

• Nginx reverse proxy
• SSL certificate generation and renewal
• WebSocket support
• Gzip compression

Step 5: Deploy

1. Click Deploy
2. Coolify will:
   • Clone the repository
   • Build the Docker image
   • Start the container
   • Run health checks
3. Wait for the "Healthy" status

Step 6: Initial Setup

6.1 Create Admin User

Run the seed script inside the container:

# In Coolify dashboard, go to your app → "Execute Command" or use terminal
docker exec -it opencodehub bun run scripts/seed-admin.ts

Or via Coolify's web terminal:

1. Go to your app → Terminal
2. Run: bun run scripts/seed-admin.ts
3. Enter username, email, and password when prompted

6.2 Verify Installation

Visit https://git.yourdomain.com and log in with the admin credentials.

Test the API health endpoint:

curl https://git.yourdomain.com/api/health

Step 7: Enable CI/CD Runner (Optional)

If you want to run CI/CD pipelines:

1. Go to your project → Resources → Add New Resource
2. Select Docker Compose → Existing Docker Compose
3. Add the runner service to your compose:

  runner:
    build:
      context: .
      dockerfile: Dockerfile.runner
    container_name: opencodehub-runner
    restart: unless-stopped
    privileged: true
    environment:
      - RUNNER_TOKEN=${RUNNER_TOKEN}
      - SERVER_URL=https://git.yourdomain.com
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - runner-work:/work
      - runner-cache:/cache

volumes:
  runner-work:
  runner-cache:

4. Get the runner token from OpenCodeHub admin panel → Runners → Register Runner
5. Add RUNNER_TOKEN to environment variables
6. Deploy the updated compose

Step 8: Automated Deployments (GitHub Integration)

8.1 Enable Auto-Deploy

1. In Coolify, go to your app → Settings → Git
2. Enable Auto Deploy on Push
3. Coolify will automatically rebuild and redeploy on every push to main

8.2 Preview Deployments (Optional)

For pull request previews:

1. Go to Settings → Preview Deployments
2. Enable Pull Request Previews
3. Each PR will get a unique URL like pr-123.git.yourdomain.com

Maintenance

Backup

Coolify has built-in backup for databases. To back up volumes:

# On your server
docker run --rm -v opencodehub-repos:/data -v $(pwd):/backup alpine tar czf /backup/repos-backup.tar.gz -C /data .
docker run --rm -v opencodehub-storage:/data -v $(pwd):/backup alpine tar czf /backup/storage-backup.tar.gz -C /data .

Update OpenCodeHub

1. Push new code to your fork/main branch
2. Coolify auto-deploys, OR
3. In Coolify dashboard → your app → Deploy

Monitor Logs

In Coolify dashboard:

• Go to your app → Logs
• Real-time logs with filtering
• Access historical logs

Troubleshooting

Architecture on Coolify

Internet
    |
    v
Cloudflare (optional)
    |
    v
Coolify Server
    |-- Coolify Proxy (Nginx + SSL)
    |-- OpenCodeHub App (Docker)
    |   |-- Port 4321: Web UI + API
    |   |-- Port 2222: SSH Git
    |-- PostgreSQL (managed)
    |-- Redis (managed)
    |-- OpenCodeHub Runner (optional, privileged Docker)

Next Steps

• Configure Email (SMTP)
• Set up Storage Adapter (S3/R2)
• Enable Branch Protection
• Set up your First Stack