docs/DEPLOYMENT.md

CodeSync — Deployment Guide

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌──────────────┐
│    Vercel        │     │  Railway/Render  │     │   Upstash    │
│  (Frontend)      │────>│  (Backend)       │────>│   Redis      │
│  Next.js SSR     │     │  Express+Socket  │     │   (Pub/Sub)  │
└─────────────────┘     └────────┬─────────┘     └──────────────┘
                                  │
                         ┌────────┴─────────┐
                         │  Supabase/Neon   │
                         │  (PostgreSQL)    │
                         └──────────────────┘

Step 1: Database Setup (Supabase)

1. Create a Supabase project at https://supabase.com
2. Copy the connection string from Settings → Database
3. Run migrations:

   cd apps/server
   npx prisma migrate deploy
   

Step 2: Redis Setup (Upstash)

1. Create a Redis database at https://console.upstash.com
2. Select the region closest to your backend server
3. Copy the REST URL and token
4. Enable "Eviction" for memory management

Step 3: Backend Deployment (Railway)

Using Railway CLI:

# Install Railway CLI
npm i -g @railway/cli

# Login and create project
railway login
railway init

# Set environment variables
railway variables set NODE_ENV=production
railway variables set PORT=4000
railway variables set DATABASE_URL="postgresql://..."
railway variables set UPSTASH_REDIS_URL="https://..."
railway variables set UPSTASH_REDIS_TOKEN="..."
railway variables set JWT_ACCESS_SECRET="$(openssl rand -base64 64)"
railway variables set JWT_REFRESH_SECRET="$(openssl rand -base64 64)"
railway variables set CLIENT_URL="https://your-app.vercel.app"
railway variables set OPENROUTER_API_KEY="..."

# Deploy
railway up

Using Render:

1. Connect GitHub repository
2. Select apps/server as the root directory
3. Build command: npm run build
4. Start command: npm start
5. Add environment variables in the dashboard

Step 4: Frontend Deployment (Vercel)

# Install Vercel CLI
npm i -g vercel

# Deploy
cd apps/web
vercel

# Set environment variable
vercel env add NEXT_PUBLIC_API_URL
# Enter your Railway/Render backend URL

Vercel Configuration:

• Framework: Next.js
• Root Directory: apps/web
• Build Command: next build
• Output Directory: .next

Step 5: Docker Sandbox Setup

For code execution to work, the backend server needs Docker access:

Option A: Railway with Docker (recommended)

Railway supports Docker-in-Docker. Mount the Docker socket.

Option B: Separate execution service

Deploy a dedicated execution microservice on a VPS with Docker:

# On a VPS (DigitalOcean, Hetzner, etc.)
docker compose -f docker/docker-compose.execution.yml up -d

Option C: Use a managed service

Use Judge0 API or Piston for code execution without managing Docker.

Step 6: Google OAuth Setup

1. Go to https://console.cloud.google.com
2. Create OAuth 2.0 credentials
3. Add authorized redirect: https://your-backend.railway.app/api/auth/google/callback
4. Add authorized origin: https://your-app.vercel.app

Step 7: Build Sandbox Images

cd docker/sandboxes
docker build -t codesync-sandbox-js ./javascript
docker build -t codesync-sandbox-python ./python
docker build -t codesync-sandbox-cpp ./cpp
docker build -t codesync-sandbox-java ./java

Environment Variables Checklist

Variable	Required	Service
DATABASE_URL	✅	Supabase
UPSTASH_REDIS_URL	✅	Upstash
UPSTASH_REDIS_TOKEN	✅	Upstash
JWT_ACCESS_SECRET	✅	Generate
JWT_REFRESH_SECRET	✅	Generate
CLIENT_URL	✅	Vercel URL
OPENROUTER_API_KEY	Optional	OpenRouter
GOOGLE_CLIENT_ID	Optional	Google Cloud
GOOGLE_CLIENT_SECRET	Optional	Google Cloud

Performance Optimization

1. WebSocket Sticky Sessions: Not needed — Redis pub/sub handles cross-instance communication
2. Connection Pooling: Use PgBouncer or Supabase's built-in pooler
3. CDN: Vercel Edge Network handles static assets automatically
4. Rate Limiting: Redis-backed distributed rate limiting works across instances

Scaling Strategy

• Horizontal Backend Scaling: Add more Railway/Render instances. Redis pub/sub ensures all instances share state.
• Database Scaling: Use read replicas for queries, primary for writes
• WebSocket Scaling: Each instance handles up to ~10K concurrent connections
• Code Execution: Queue-based with separate worker pool

Monitoring

• Use Railway/Render built-in metrics
• Set up Upstash Redis monitoring dashboard
• Add application logging with structured JSON output
• Consider adding Sentry for error tracking