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:
   ```bash
   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:
```bash
# 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)

```bash
# 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:
```bash
# 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

```bash
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