Coolify Deployment - RippleCore Documentation

Overview

Coolify is a self-hosted platform-as-a-service (PaaS) similar to Dokploy but with more features including built-in monitoring, database backups, and GitHub Actions integration.

Recommended upgrade from Dokploy if you need better monitoring, backups, and more integration options.

Why Coolify?

Better UI/UX

More polished interface than Dokploy

Built-in Monitoring

Comprehensive metrics and log aggregation

Automatic Backups

Database backups with S3 integration

GitHub Actions

Advanced CI/CD integration

Comparison vs Dokploy

Feature	Dokploy	Coolify
Web UI	Good	Excellent
SSL Management	✅ Let’s Encrypt	✅ Let’s Encrypt
Monitoring	Basic	Advanced
Database Backups	Manual	Automated
GitHub Integration	Basic	GitHub Actions
Multi-Server	No	Yes
Resource Overhead	Medium	Medium-High
Community	Growing	Mature

Prerequisites

Same as Dokploy:

Hetzner CPX32 (4 vCPU, 8GB RAM) or equivalent
Ubuntu 24.04 LTS
Root access
Domain with DNS access

Installation

Step 1: Prepare VPS

# SSH into VPS
ssh root@your-vps-ip

# Update system
apt update && apt upgrade -y

# Install essentials
apt install -y curl wget git

Step 2: Configure Firewall

ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP
ufw allow 443/tcp   # HTTPS
ufw allow 8000/tcp  # Coolify dashboard
ufw enable

Step 3: Install Docker

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Enable Docker
systemctl enable docker
systemctl start docker

Step 4: Install Coolify

One-line installer:

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

Installation takes ~7-10 minutes. The installer will:

Install Docker (if needed)
Set up Coolify containers
Configure Traefik reverse proxy
Initialize PostgreSQL for Coolify metadata
Set up monitoring stack

Step 5: Access Dashboard

http://your-vps-ip:8000

Create admin account:

Email: your-email@example.com
Password: Strong password (save to password manager)

Coolify runs on port 8000 by default. You can configure a custom domain for the dashboard.

Initial Configuration

1. Connect Git Provider

Settings → Git Sources → Add New
Select GitHub or GitLab
Generate Personal Access Token (PAT)
Paste token and save

GitHub PAT Permissions:

repo (full control)
read:packages
write:packages

2. Configure Email (Optional)

For deployment notifications:

Settings → Email Configuration
Add SMTP details (e.g., Gmail, SendGrid)
Test email delivery

3. Set Up S3 Backup Storage (Optional)

For automated database backups:

Settings → Backup
Add S3 credentials:
- Access Key ID
- Secret Access Key
- Bucket name
- Region

You can use AWS S3, Backblaze B2, or any S3-compatible storage.

Deployment Workflow

Phase 1: Infrastructure

1. PostgreSQL 18

Resources → New → Database → PostgreSQL

Configuration:

Name: ripplecore-postgres
Version: 18
Database: ripplecore
Username: ripplecore
Password: [Auto-generated or custom]
Port: 5432

Storage:

Enable Persistent Volume: Yes
Volume Size: 20GB

Backups (Coolify feature):

Enable Automated Backups: Yes
Frequency: Daily at 2:00 AM
Retention: 7 days
Destination: S3 bucket

Deploy

Connection String:

postgresql://ripplecore:PASSWORD@ripplecore-postgres:5432/ripplecore

2. Redis 7

Resources → New → Database → Redis

Configuration:

Name: ripplecore-redis
Version: 7-alpine
Password: [Auto-generated]
Port: 6379
Persistent Volume: Yes

Deploy

Connection String:

redis://:PASSWORD@ripplecore-redis:6379

Phase 2: Migrations

Resources → New → Application

Git Source:

Repository: https://github.com/your-username/ripplecore-forge
Branch: main
Build Pack: Dockerfile
Dockerfile: apps/migrations/Dockerfile
Build Context: .

Environment Variables:

DATABASE_URL=postgresql://ripplecore:PASSWORD@ripplecore-postgres:5432/ripplecore
NODE_ENV=production

Advanced:

Type: One-time Job
Restart Policy: Never
Resources:
  CPU: 0.5
  Memory: 512MB

Deploy and monitor logs

Phase 3: Applications

Main App

Resources → New → Application

Git Source:

Repository: ripplecore-forge
Branch: main
Auto Deploy: Yes (on push to main)
Build Pack: Dockerfile
Dockerfile: apps/app/Dockerfile
Build Context: .

Build Arguments:

DATABASE_URL=postgresql://ripplecore:PASSWORD@ripplecore-postgres:5432/ripplecore
REDIS_URL=redis://:PASSWORD@ripplecore-redis:6379
BETTER_AUTH_SECRET=[Generate with: npx @better-auth/cli secret]
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_WEB_URL=https://yourdomain.com

Environment Variables:

# Infrastructure
DATABASE_URL=postgresql://ripplecore:PASSWORD@ripplecore-postgres:5432/ripplecore
REDIS_URL=redis://:PASSWORD@ripplecore-redis:6379

# Auth
BETTER_AUTH_SECRET=YOUR_SECRET
BETTER_AUTH_URL=https://app.yourdomain.com
BETTER_AUTH_TRUST_HOST=true

# URLs
NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
NEXT_PUBLIC_WEB_URL=https://yourdomain.com

# System
NODE_ENV=production
PORT=3000

Domain:

Domain: app.yourdomain.com
Force HTTPS: Yes
Generate SSL: Yes (Let's Encrypt)

Health Check:

Enabled: Yes
Path: /api/health
Port: 3000
Interval: 30s
Timeout: 10s
Retries: 3

Resources:
```
CPU: 1.0
Memory: 1GB
```
Deploy

API Service

Follow same pattern with:

Name: ripplecore-api
Dockerfile: apps/api/Dockerfile
Domain: api.yourdomain.com
Port: 3002

Marketing Website

Name: ripplecore-web
Dockerfile: apps/web/Dockerfile
Domain: yourdomain.com, www.yourdomain.com
Port: 3001

Environment:
  NEXT_PUBLIC_APP_URL=https://app.yourdomain.com
  NEXT_PUBLIC_WEB_URL=https://yourdomain.com
  NODE_ENV=production
  PORT=3001

GitHub Actions Integration

Coolify supports advanced CI/CD with GitHub Actions:

1. Generate Coolify API Token

Settings → API Tokens → Generate New
Copy token (save securely)

2. Add GitHub Secrets

In GitHub repository:

Settings → Secrets and variables → Actions

Add secrets:

COOLIFY_API_TOKEN=your_coolify_token
COOLIFY_WEBHOOK_URL=https://coolify.yourdomain.com/api/webhooks/deploy

3. Create Workflow

.github/workflows/deploy.yml:

name: Deploy to Coolify

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Coolify Deployment
        run: |
          curl -X POST ${{ secrets.COOLIFY_WEBHOOK_URL }} \
            -H "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{"branch":"main"}'

Now every push to main automatically triggers Coolify deployment.

Monitoring & Logs

Built-in Metrics

Coolify dashboard shows:

CPU usage per container
Memory usage per container
Network I/O
Disk usage
Request rate
Response times

Log Aggregation

Resources → [app-name] → Logs
View real-time logs with filtering:
- Search by keyword
- Filter by log level
- Time range selection
- Export logs

Alerts

Configure notifications:

Settings → Notifications
Add notification channels:
- Email
- Slack
- Discord
- Telegram
- Webhook
Set up alerts for:
- Deployment failures
- Health check failures
- High CPU/Memory usage
- Disk space warnings

Database Backups

Automated Backups

Resources → ripplecore-postgres → Backups

Configuration:

Schedule: Daily at 2:00 AM UTC
Retention: 7 days
Destination: S3 bucket
Compression: gzip
Encryption: AES-256

Save and enable

Manual Backup

Resources → ripplecore-postgres → Backups
Create Backup Now
Download or send to S3

Restore from Backup

Resources → ripplecore-postgres → Backups
Select backup
Restore
Confirm (this will replace current database)

Always test backup restoration in a staging environment before production.

Migration from Dokploy

Parallel Testing Approach (Recommended)

Keep Dokploy running on main VPS
Spin up new VPS (Hetzner CX22, €4.49/month)
Install Coolify on test VPS
Deploy RippleCore to Coolify
Test thoroughly (functionality, performance)
Compare experience and features
Decide migration path

Direct Migration Steps

If migrating from Dokploy to Coolify on same VPS:

1. Export Dokploy Data

# Backup PostgreSQL
docker exec ripplecore-postgres pg_dump -U ripplecore ripplecore > backup.sql

# Export environment variables
# Save from Dokploy dashboard

2. Stop Dokploy

# Stop Dokploy services
docker stop $(docker ps -q)

# Optional: Remove Dokploy
docker rm $(docker ps -aq)

3. Install Coolify

Follow installation steps above.

4. Restore Data

# Import database
cat backup.sql | docker exec -i ripplecore-postgres psql -U ripplecore ripplecore

5. Deploy Applications

Follow deployment workflow above. Estimated migration time: 2-3 hours

DNS Cutover

If using different VPS:

Deploy everything to new VPS
Test with /etc/hosts override
Update DNS A records to new IP
Wait for propagation (1-48 hours)
Monitor new VPS for 24 hours
Decommission old VPS

Troubleshooting

Build Failures

Issue: Build failing in CoolifyCheck:

Build context is . (monorepo root)
Dockerfile path is correct
Build arguments are set
Logs show specific error

Debug:

# View build logs in Coolify UI
Resources → [app] → Deployments → [latest] → Logs

SSL Certificate Issues

Issue: Let’s Encrypt SSL failingFix:

Verify DNS points to VPS: dig app.yourdomain.com
Check port 80/443 open: ufw status
Wait for DNS propagation
Check Coolify logs: Settings → Logs

Database Connection Failed

Issue: Apps can’t connect to PostgreSQLFix:

Verify connection string format
Check PostgreSQL is running: docker ps | grep postgres

Test connection:

docker exec -it ripplecore-postgres psql -U ripplecore

GitHub Actions Not Triggering

Issue: Webhook not deployingFix:

Verify API token is correct
Check GitHub webhook delivery logs
Ensure Coolify webhook URL is accessible

Test webhook manually:

curl -X POST https://coolify.yourdomain.com/api/webhooks/deploy \
  -H "Authorization: Bearer YOUR_TOKEN"

Performance Optimization

Resource Allocation

Recommended for Hetzner CPX32:

PostgreSQL: 1 GB RAM, 0.5 vCPU
Redis: 512 MB RAM, 0.25 vCPU
App: 1 GB RAM, 1.0 vCPU
API: 1 GB RAM, 1.0 vCPU
Web: 512 MB RAM, 0.5 vCPU
Docs: 256 MB RAM, 0.25 vCPU
Coolify: 1.5 GB RAM, 0.5 vCPU
System: 2 GB RAM, 0.5 vCPU

Total: 7.75 GB RAM, 4.0 vCPU

Caching Strategy

Coolify supports Redis caching (already configured in RippleCore):

Evidence data: 5-minute TTL
Session data: 8-hour TTL
Static assets: CDN integration

CDN Integration

For static assets:

Resources → [app] → Storage
Configure S3-compatible CDN
Set cache headers
Enable compression

Pros & Cons

Advantages

Better UI than Dokploy
Advanced monitoring
Automated backups
GitHub Actions
Multi-server support
Active community

Limitations

More resource overhead
Steeper learning curve
More complex setup
Higher memory usage

Cost Comparison

Hetzner CPX32 (€11.99/month)

Dokploy:

App overhead: ~500MB RAM
Total available: ~7.5GB RAM for apps

Coolify:

App overhead: ~1.5GB RAM
Total available: ~6.5GB RAM for apps

Conclusion: Coolify uses ~1GB more RAM for platform overhead.

With S3 Backups

Backblaze B2 (cheapest):

10GB storage: ~€0.50/month
Download: €0.01/GB

AWS S3:

10GB storage: ~€2.30/month
Download fees apply

When to Choose Coolify

Choose Coolify over Dokploy if:

✅ You need built-in monitoring
✅ Automated backups are critical
✅ Using GitHub Actions for CI/CD
✅ Planning multi-server deployment
✅ Want better UI/UX experience
✅ Need advanced notification system

Stick with Dokploy if:

⚠️ Current setup works well
⚠️ Team prefers simpler platform
⚠️ Don’t need advanced features
⚠️ Want to minimize resource overhead

Next Steps

Test in Parallel

Deploy Coolify on test VPS (CX22, €4.49/month)

Migrate from Dokploy

Follow migration guide above

Set Up Monitoring

Configure alerts and log aggregation

Configure Backups

Set up automated S3 backups

Coolify provides the best balance of features and simplicity for teams ready to upgrade from Dokploy.

Get Started

User Guides

Admin Portal

Compliance & Reporting

All We Can Integration

Deployment

​Overview

​Why Coolify?

Better UI/UX

Built-in Monitoring

Automatic Backups

GitHub Actions

​Comparison vs Dokploy

​Prerequisites

​Installation

​Step 1: Prepare VPS

​Step 2: Configure Firewall

​Step 3: Install Docker

​Step 4: Install Coolify

​Step 5: Access Dashboard

​Initial Configuration

​1. Connect Git Provider

​2. Configure Email (Optional)

​3. Set Up S3 Backup Storage (Optional)

​Deployment Workflow

​Phase 1: Infrastructure

​1. PostgreSQL 18

​2. Redis 7

​Phase 2: Migrations

​Phase 3: Applications

​Main App

​API Service

​Marketing Website

​GitHub Actions Integration

​1. Generate Coolify API Token

​2. Add GitHub Secrets

​3. Create Workflow

​Monitoring & Logs

​Built-in Metrics

​Log Aggregation

​Alerts

​Database Backups

​Automated Backups

​Manual Backup

​Restore from Backup

​Migration from Dokploy

​Parallel Testing Approach (Recommended)

​Direct Migration Steps

​1. Export Dokploy Data

​2. Stop Dokploy

​3. Install Coolify

​4. Restore Data

​5. Deploy Applications

​DNS Cutover

​Troubleshooting

​Performance Optimization

​Resource Allocation

​Caching Strategy

​CDN Integration

​Pros & Cons

Advantages

Limitations

​Cost Comparison

​Hetzner CPX32 (€11.99/month)

​With S3 Backups

​When to Choose Coolify

​Next Steps

Test in Parallel

Migrate from Dokploy

Set Up Monitoring

Configure Backups

Overview

Why Coolify?

Comparison vs Dokploy

Prerequisites

Installation

Step 1: Prepare VPS

Step 2: Configure Firewall

Step 3: Install Docker

Step 4: Install Coolify

Step 5: Access Dashboard

Initial Configuration

1. Connect Git Provider

2. Configure Email (Optional)

3. Set Up S3 Backup Storage (Optional)

Deployment Workflow

Phase 1: Infrastructure

1. PostgreSQL 18

2. Redis 7

Phase 2: Migrations

Phase 3: Applications

Main App

API Service

Marketing Website

GitHub Actions Integration

1. Generate Coolify API Token

2. Add GitHub Secrets

3. Create Workflow

Monitoring & Logs

Built-in Metrics

Log Aggregation

Alerts

Database Backups

Automated Backups

Manual Backup

Restore from Backup

Migration from Dokploy

Parallel Testing Approach (Recommended)

Direct Migration Steps

1. Export Dokploy Data

2. Stop Dokploy

3. Install Coolify

4. Restore Data

5. Deploy Applications

DNS Cutover

Troubleshooting

Performance Optimization

Resource Allocation

Caching Strategy

CDN Integration

Pros & Cons

Cost Comparison

Hetzner CPX32 (€11.99/month)

With S3 Backups

When to Choose Coolify

Next Steps