Production Deployment

This guide covers deploying Traces to production.

Infrastructure Overview

Traces uses the following cloud services:

Service	Provider	Purpose
Web Application	Vercel	Next.js frontend hosting
Worker	Railway	Background job processing
Database + Queue	Supabase	PostgreSQL database; job queue via pg-boss
Cache (optional)	Upstash / any Redis	Worker status cache (graceful no-op if absent)
Storage	Cloudflare R2	File storage
Secrets	AWS Secrets Manager	Credential storage
Auth	Clerk	User authentication

The job queue is pg-boss, which runs inside the same Postgres database (in the pgboss schema) — there is no separate Redis queue service. Redis is used only as an optional worker-side status cache.

Deployment Steps

1. Database (Supabase)

1. Create a new Supabase project
2. Note both connection strings from Settings → Database — the pooled URL (...pooler.supabase.com:6543, used at runtime) and the direct URL (db.<ref>.supabase.co:5432, used for migrations/DDL)
3. Run migrations (migrations use DIRECT_URL):

DATABASE_URL="postgresql://...:6543/postgres?pgbouncer=true" \
DIRECT_URL="postgresql://...:5432/postgres" \
  pnpm --filter @traces/database db:migrate:deploy

2. Queue (pg-boss)

The job queue runs on Postgres via pg-boss — no separate service is required. On first run it creates a pgboss schema in the same database. Just ensure the worker and web app share the same DATABASE_URL.

Optionally, provision a Redis instance (e.g. Upstash) and set REDIS_URL on the worker to enable the status cache. If unset, the worker falls back to reading status from Postgres directly.

3. Storage (Cloudflare R2)

1. Create an R2 bucket
2. Generate API tokens with read/write access
3. Configure CORS if needed for direct uploads

4. Secrets Manager (AWS)

1. Create IAM user with Secrets Manager access
2. Generate access keys
3. Configure region (recommend same as other services)

5. Authentication (Clerk)

1. Create Clerk application
2. Configure OAuth providers
3. Set up webhooks for user events
4. Note publishable and secret keys

6. Web Application (Vercel)

# Install Vercel CLI
npm i -g vercel

# Deploy
cd apps/web
vercel --prod

Configure environment variables in Vercel dashboard.

7. Worker (Railway)

1. Connect GitHub repository
2. Set root directory to apps/worker
3. Configure environment variables
4. Deploy

Environment Variables

Web Application

# Database
DATABASE_URL="postgresql://..."

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."
CLERK_SECRET_KEY="sk_live_..."
CLERK_WEBHOOK_SECRET="whsec_..."

# R2 Storage
R2_ACCESS_KEY_ID="..."
R2_SECRET_ACCESS_KEY="..."
R2_BUCKET="traces-prod"
R2_ENDPOINT="https://..."
R2_PUBLIC_URL="https://..."

# Anthropic (connector generation, docs discovery, suggestions)
ANTHROPIC_API_KEY="sk-ant-..."

# App
NEXT_PUBLIC_APP_URL="https://app.traces.io"

Worker

# Database (must match the web app — pg-boss runs here too)
DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."     # for any migrations run from the worker host

# Redis (optional — status cache only; omit to disable)
REDIS_URL="rediss://..."

# AWS Secrets Manager
AWS_ACCESS_KEY_ID="..."
AWS_SECRET_ACCESS_KEY="..."
AWS_REGION="us-east-1"

# R2 Storage
R2_ACCESS_KEY_ID="..."
R2_SECRET_ACCESS_KEY="..."
R2_BUCKET="traces-prod"
R2_ENDPOINT="https://..."

Monitoring

Health Checks

• Web: https://app.traces.io/api/health
• Worker: Internal health check on Railway

Logging

• Vercel: Built-in logging dashboard
• Railway: Built-in logging dashboard
• Consider adding Sentry for error tracking

Metrics

Recommended metrics to track:

• Collection completion rate
• Average collection duration
• API response times
• Worker queue depth
• Error rates by type

Scaling

Web Application

Vercel automatically scales based on traffic.

Worker

For high-volume deployments:

1. Increase Railway instance size
2. Run multiple worker replicas
3. Consider dedicated queues for different job types

Database

Supabase scaling options:

1. Upgrade plan for more connections
2. Enable connection pooling
3. Add read replicas for reporting

Security Checklist

• All secrets in environment variables (not code)
• HTTPS enforced on all endpoints
• Database connections use SSL
• R2 bucket is not publicly accessible
• Clerk webhook signature verification enabled
• Rate limiting configured
• CORS policies configured correctly
• Regular security updates applied

Backup and Recovery

Database

• Supabase provides automatic daily backups
• Configure point-in-time recovery for critical data
• Test restore procedures regularly

File Storage

• R2 provides 99.999999999% durability
• Consider cross-region replication for critical files

Next Steps

• Troubleshooting Guide
• Monitoring Setup