Skip to main content

Deployment Guide

Deploy Korad.AI to production using Fly.io (backend) and Vercel (frontend).

Architecture​

┌─────────────────────────────────────────────────────────┐
│                      Users                              │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Vercel (user-portal)                                   │
│  - Landing page                                         │
│  - Dashboard                                            │
│  - Admin panel                                          │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Fly.io (API)                                           │
│  - /v1/messages (Anthropic-compatible)                 │
│  - /webhooks/stripe (Payment processing)               │
│  - /webhooks/clerk (User provisioning)                 │
│  - /admin/* (Admin endpoints)                          │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Neon (Database)                                        │
│  - Users                                                │
│  - Transactions                                         │
│  - API keys                                             │
└─────────────────────────────────────────────────────────┘

Backend Deployment (Fly.io)​

Prerequisites​

# Install Fly.io CLI
curl -L https://fly.io/install.sh | sh

# Login
flyctl auth login

Create App​

# Create production app
flyctl apps create excell-ai-prod

# Create staging app
flyctl apps create excell-ai-staging

Configure Secrets​

# Production
flyctl secrets set DATABASE_URL=... --app excell-ai-prod
flyctl secrets set LITELLM_MASTER_KEY=... --app excell-ai-prod
flyctl secrets set STRIPE_SECRET_KEY=... --app excell-ai-prod
flyctl secrets set STRIPE_WEBHOOK_SECRET=... --app excell-ai-prod
flyctl secrets set CLERK_SECRET_KEY=... --app excell-ai-prod
flyctl secrets set CLERK_WEBHOOK_SECRET=... --app excell-ai-prod
flyctl secrets set INITIAL_CREDIT=0.0 --app excell-ai-prod

# Staging
flyctl secrets set DATABASE_URL=... --app excell-ai-staging
flyctl secrets set LITELLM_MASTER_KEY=... --app excell-ai-staging
# ... (same as production)

Deploy​

# Deploy to production
flyctl deploy --app excell-ai-prod --remote-only

# Deploy to staging
flyctl deploy --app excell-ai-staging --remote-only

Configure Fly.toml​

# fly-prod.toml
app = "excell-ai-prod"
primary_region = "sjc"

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"
  ENVIRONMENT = "production"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false
  min_machines_running = 1

[[http_service.checks]]
  interval = "60s"
  timeout = "10s"
  grace_period = "10s"
  method = "GET"
  path = "/health"

[[vm]]
  size = "shared-cpu-2x"
  memory_mb = 1024

Monitor Deployment​

# View logs
flyctl logs --app excell-ai-prod

# Check status
flyctl status --app excell-ai-prod

# Open dashboard
flyctl dashboard --app excell-ai-prod

Frontend Deployment (Vercel)​

Connect Repository​

  1. Go to vercel.com
  2. Click "New Project"
  3. Import GitHub repository: WeathermanTony/korad.ai
  4. Select user-portal/ as root directory

Configure Build​

Framework Preset: Next.js
Build Command: npm run build
Output Directory: .next
Install Command: npm install

Environment Variables​

# In Vercel dashboard → Settings → Environment Variables
NEXT_PUBLIC_API_URL=https://api.korad.ai
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

Deploy​

Click "Deploy" — Vercel auto-deploys on push to main.

Custom Domain​

  1. Go to project Settings → Domains
  2. Add korad.ai
  3. Configure DNS (Vercel provides instructions)

Documentation Deployment (Vercel)​

Deploy Docusaurus​

  1. Go to vercel.com
  2. Click "New Project"
  3. Import WeathermanTony/korad.ai
  4. Select docusaurus-docs/ as root directory

Configure Build​

Framework Preset: Other
Build Command: npm run build
Output Directory: build
Install Command: npm install

Custom Domain​

Add docs.korad.ai in project settings.

GitHub Actions (CI/CD)​

Backend Workflow​

.github/workflows/backend.yml automatically:

  • Runs tests on push/PR
  • Deploys to staging on staging branch
  • Deploys to production on main branch

Frontend Workflow​

.github/workflows/frontend.yml automatically:

  • Runs tests on push/PR
  • Deploys preview on PR
  • Deploys to production on main branch

Monitoring​

Backend Health​

# Health check endpoint
curl https://api.korad.ai/health

# Response
{"status": "healthy", "version": "1.1.0"}

Error Tracking​

Configure Sentry or similar in start.py:

import sentry_sdk

sentry_sdk.init(
    dsn="your-sentry-dsn",
    environment="production"
)

Logging​

Logs are available via:

# Fly.io logs
flyctl logs --app excell-ai-prod

# Or use a logging service (Datadog, LogRocket, etc.)

Scaling​

Vertical Scaling​

# Increase machine size
flyctl scale vm shared-cpu-4x --app excell-ai-prod

Horizontal Scaling​

# Increase machine count
flyctl scale count 3 --app excell-ai-prod

Regions​

Deploy to multiple regions:

flyctl regions add sjc --app excell-ai-prod
flyctl regions add lax --app excell-ai-prod

Rollback​

Backend​

# View releases
flyctl releases --app excell-ai-prod

# Rollback to specific release
flyctl releases rollback <VERSION> --app excell-ai-prod

Frontend​

Go to Vercel dashboard → Deployments → Click "Rollback" on previous deployment.

Best Practices​

  1. Test on staging first — Always deploy to staging before production
  2. Monitor after deployment — Check logs and health for 10 minutes
  3. Have rollback plan — Know how to rollback quickly
  4. Tag releases — Use git tags for production releases
  5. Monitor costs — Check Fly.io and Vercel usage dashboards

Troubleshooting​

Deployment Failed​

  1. Check build logs in GitHub Actions
  2. Verify environment variables are set
  3. Check for syntax errors in code
  4. Ensure tests pass locally

Health Check Failing​

# Check if app is running
flyctl status --app excell-ai-prod

# Check logs for errors
flyctl logs --app excell-ai-prod

Database Connection Failed​

# Verify DATABASE_URL secret
flyctl secrets list --app excell-ai-prod

# Test connection
psql $DATABASE_URL

Development Setup → Stripe Testing →