scientiacapital/deployment-patterns

Deployment Patterns for Scientia Stack

Deploy to Vercel, Railway, or Docker following proven patterns from 98+ projects.

Platform Selection

Choose based on project type:

| Project Type | Platform | Reason | |--------------|----------|--------| | Next.js frontend | Vercel | Native support, edge functions | | Python backend | Railway | Nixpacks, health checks | | ML/GPU workloads | RunPod | GPU access, vLLM | | Local development | Docker | Consistent environment |

Vercel Deployment (19 projects)

Standard vercel.json for Monorepo

{
  "framework": "nextjs",
  "installCommand": "cd frontend && npm install",
  "buildCommand": "cd frontend && npm run build",
  "outputDirectory": "frontend/.next"
}

Environment Variables

1. Set in Vercel Dashboard or CLI:

   vercel env add VITE_SUPABASE_URL production
   vercel env add VITE_SUPABASE_ANON_KEY production
   

2. For preview deployments, use preview scope.

SPA Routing

Add to frontend/vercel.json:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

Deploy Command

# Production
vercel --prod

# Preview
vercel

Railway Deployment (2 projects)

Standard railway.json

{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "poetry install --no-dev"
  },
  "deploy": {
    "startCommand": "poetry run python -m src.vozlux.main",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Environment Variables

Railway requires manual dashboard configuration for sensitive vars:

• Go to: https://railway.com/project/{project-id}/settings
• Add each variable under "Variables" tab

Common variables for Python backends:

SUPABASE_URL
SUPABASE_SERVICE_KEY
ANTHROPIC_API_KEY
GOOGLE_API_KEY
DEEPSEEK_API_KEY
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN

Health Check Endpoint

Always implement /health:

@app.get("/health")
async def health():
    return {"status": "healthy", "timestamp": datetime.utcnow().isoformat()}

Docker Deployment (5 projects)

Multi-stage Dockerfile

# Build stage
FROM python:3.11-slim as builder
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry export -f requirements.txt > requirements.txt

# Runtime stage
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /app/requirements.txt .
RUN pip install -r requirements.txt
COPY src/ ./src/
CMD ["python", "-m", "src.main"]

docker-compose.yml for Development

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./src:/app/src

Pre-Deployment Checklist

Before any deployment:

1. [ ] All tests passing (npm test or pytest)
2. [ ] No hardcoded API keys (grep for patterns)
3. [ ] Environment variables documented in .env.example
4. [ ] CLAUDE.md updated with deployment status
5. [ ] Build succeeds locally (npm run build or poetry build)

Debugging Deployment Failures

Vercel Failures

1. Check build logs: vercel logs
2. Common issues:
   • Missing env vars → Check Vercel dashboard
   • Build timeout → Increase in project settings
   • Module not found → Check package.json dependencies

Railway Failures

1. Check logs in dashboard
2. Common issues:
   • Health check timeout → Increase healthcheckTimeout
   • Missing env vars → Must set manually in dashboard
   • Poetry lock issues → Delete poetry.lock and regenerate

Docker Failures

1. Build locally first: docker build -t test .
2. Run with logs: docker run -it test
3. Check for missing system dependencies

CI/CD Integration

For GitHub Actions, use:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'