​
Coolify Deployment Guide

Deploy your TurboStack project to Coolify - a self-hosted alternative to Heroku/Vercel.
Coolify is an open-source platform that lets you deploy applications using Docker. This guide covers deploying both frontend and backend applications.

​
Prerequisites

Coolify Account

Sign up at coolify.io or self-host

Git Repository

Your code must be in a Git repository (GitHub, GitLab, etc.)

PostgreSQL

Available through Coolify or external provider

Domain (Optional)

Custom domain for production deployment

​
Deployment Architecture

Coolify automatically handles SSL certificates, reverse proxy, and internal networking between services.

​
Step 1: Create Project

1

Login to Coolify

Access your Coolify dashboard
2

Create New Project

Click “New Project” and name it turbostack

​
Step 2: Setup Database

1

Create PostgreSQL Service

  1. Select “New Resource” → “Database”
  2. Choose PostgreSQL 16
  3. Configure:
    • Name: turbostack-db
    • Database: turbostack
    • Username: turbostack
    • Password: Generate strong password
2

Note Connection Details

After creation, save these details:
Host: db (internal network)
Port: 5432
Database: turbostack
User: turbostack
Password: [your-password]
Connection String:
postgresql://turbostack:[password]@db:5432/turbostack

​
Step 3: Deploy Backend API

1

Create API Application

  1. Select “New Resource” → “Application”
  2. Choose “Git Repository”
  3. Enter repository URL
  4. Select main branch
2

Configure Build Settings

​
Build Pack
string
required
Select Dockerfile
​
Base Directory
string
Leave EMPTY (monorepo root)
​
Dockerfile Location
string
required
Dockerfile.api
​
Port
number
required
4101
​
Health Check Path
string
/health
Base Directory MUST be empty for monorepo builds to work correctly!
3

Set Environment Variables

Add these environment variables:
# Database
DATABASE_URL=postgresql://turbostack:[password]@db:5432/turbostack

# Server
NODE_ENV=production
PORT=4101

# Security
JWT_SECRET=your-super-secret-jwt-key-minimum-32-chars
SESSION_SECRET=another-super-secret-session-key

# CORS (update after web deployment)
CORS_ORIGIN=https://your-web-domain.coolify.app

# Email (Resend)
RESEND_API_KEY=re_your_api_key
FROM_EMAIL=noreply@yourdomain.com

# Payments (Polar.sh)
POLAR_ACCESS_TOKEN=polar_at_your_token
POLAR_WEBHOOK_SECRET=polar_ws_your_secret
4

Deploy

Click “Deploy” and wait for build to complete. Coolify will:
  • Clone repository
  • Build Docker image
  • Start container
  • Generate domain (e.g., api-xxxxx.coolify.app)

​
Step 4: Deploy Frontend

1

Create Web Application

  1. Select “New Resource” → “Application”
  2. Choose “Git Repository”
  3. Same repository, main branch
2

Configure Build Settings

​
Build Pack
string
required
Select Dockerfile
​
Base Directory
string
Leave EMPTY
​
Dockerfile Location
string
required
Dockerfile.web
​
Port
number
required
4100
3

Set Environment Variables

# API Connection (use your API domain from Step 3)
NEXT_PUBLIC_API_URL=https://api-xxxxx.coolify.app

# App URL (will be provided after deployment)
FRONTEND_URL=https://web-xxxxx.coolify.app

NODE_ENV=production
4

Deploy

Click “Deploy” and wait for build to complete

​
Step 5: Update CORS Settings

After both deployments are complete:
1

Get Web Domain

Copy your frontend domain from Coolify (e.g., https://web-xxxxx.coolify.app)
2

Update API Environment

Go to API application → Environment Variables → Update:
CORS_ORIGIN=https://web-xxxxx.coolify.app
3

Redeploy API

Click “Redeploy” for changes to take effect

​
Custom Domains & SSL

1

Configure in Coolify

  1. Go to application settings
  2. Navigate to “Domains” section
  3. Add your custom domain (e.g., api.yourdomain.com)
2

Update DNS

Add A or CNAME record pointing to your Coolify server:
Type: A
Name: api
Value: [Your Coolify Server IP]
3

Enable SSL

Coolify automatically provisions Let’s Encrypt SSL certificates

​
Database Migrations

Run migrations after deployment: 
# Access API container terminal in Coolify
cd apps/backend
bun run prisma migrate deploy
Consider adding migration command to your Dockerfile startup script for automatic migrations on deploy.

​
Environment Variables Reference

DATABASE_URL=postgresql://user:pass@db:5432/turbostack
NODE_ENV=production
PORT=4101
JWT_SECRET=min-32-chars
SESSION_SECRET=min-32-chars
CORS_ORIGIN=https://your-web-domain.com
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
FRONTEND_URL=https://web.yourdomain.com NODE_ENV=production ```
</Accordion>

<Accordion title="Optional Services" icon="plug">
  ```bash
  # Email (Resend)
  RESEND_API_KEY=re_...
  FROM_EMAIL=noreply@yourdomain.com

  # Payments (Polar.sh)
  POLAR_ACCESS_TOKEN=polar_at_...
  POLAR_WEBHOOK_SECRET=polar_ws_...

  # File Upload (UploadThing)
  UPLOADTHING_SECRET=...
  UPLOADTHING_APP_ID=...

​
Troubleshooting

Cause: Base Directory is not emptySolution: Set Base Directory to empty (leave blank)
Cause: Wrong connection string or database not readySolution:
  • Verify DATABASE_URL format
  • Ensure database service is running
  • Use db as host (internal network)
Cause: Port mismatch or health check failingSolution:
  • Verify port 4101 is exposed in Dockerfile
  • Check health endpoint returns 200 OK
  • Review application logs
Cause: CORS_ORIGIN not set correctlySolution:
  • Update API CORS_ORIGIN to frontend domain
  • Redeploy API after change
  • Clear browser cache
Cause: Build taking too longSolution:
  • Increase build timeout in Coolify settings
  • Optimize Dockerfile (use build cache)
  • Use smaller base images

​
Monitoring & Logs

View real-time logs in Coolify dashboard:
  • Navigate to application
  • Click “Logs” tab
  • Filter by severity (info, warn, error)

​
Scaling & Performance

Horizontal Scaling

Deploy multiple instances behind load balancer

Vertical Scaling

Increase container resources (CPU, RAM)

Database Scaling

Use connection pooling (PgBouncer)

CDN Integration

Cache static assets globally

​
Next Steps

Monitoring

Set up application monitoring

Backups

Configure automated backups

CI/CD

Automate deployments with webhooks

Security

Harden your deployment
Pro tip: Enable auto-deploy from Git for continuous deployment. Coolify will automatically rebuild and deploy when you push to your repository.