Deploy on Coolify

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:

Variable	Value	Description
DATABASE_URL	postgresql://opencodehub:YOUR_PASS@opencodehub-postgres:5432/opencodehub	From Step 2.2
REDIS_URL	redis://:YOUR_PASS@opencodehub-redis:6379	From Step 2.3
JWT_SECRET	openssl rand -hex 32	Generate this
SESSION_SECRET	openssl rand -hex 32	Generate this
INTERNAL_HOOK_SECRET	openssl rand -hex 32	Generate this
CRON_SECRET	openssl rand -hex 32	Generate this
RUNNER_SECRET	openssl rand -hex 32	Generate this
WORKFLOW_SECRET_ENCRYPTION_KEY	openssl rand -hex 32	Generate this
SITE_URL	https://git.yourdomain.com	Your domain
COOLIFY_FQDN	Leave as-is (auto-set)	Coolify injects this

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:

Volume Name	Container Path	Purpose
opencodehub-repos	/data/repos	Git repositories
opencodehub-storage	/data/storage	File uploads
opencodehub-ssh	/data/ssh	SSH host keys
opencodehub-cache	/data/cache	Application cache

---

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

Problem	Solution
Build fails with “ConnectionRefused”	Retry the build; bun registry might be temporarily unavailable. The Dockerfile has built-in retry logic.
App shows “502 Bad Gateway”	Wait 2-3 minutes for first startup. Check logs for database connection errors.
Database connection error	Verify DATABASE_URL uses the internal Coolify service name (e.g., opencodehub-postgres).
Storage not persisting	Check that persistent volumes are mounted correctly in Coolify storage settings.
SSL not working	Ensure your domain DNS points to the Coolify server. Check Coolify’s SSL logs.
Git push over SSH fails	Ensure port 2222 is exposed and not blocked by firewall. Map it in Coolify: 2222:2222.

---

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