Deployment¶

This runbook covers how Curaway's backend, frontend, and documentation are deployed across Railway, Vercel, and GitHub Pages.

Architecture Overview¶

Backend -- Railway¶

The Curaway backend is deployed on Railway with automatic deploys triggered by pushes to the main branch.

Auto-Deploy¶

Every push to main triggers a new Railway deployment automatically. Railway builds the application using the configuration in railway.toml:

[build]
builder = "nixpacks"

[deploy]
startCommand = "uvicorn app.main:app --host 0.0.0.0 --port $PORT"
healthcheckPath = "/ready"
healthcheckTimeout = 300
restartPolicyType = "on_failure"
restartPolicyMaxRetries = 3

Health Check¶

Railway monitors the /ready endpoint to determine if the deployment is healthy. This endpoint performs lightweight checks:

• Database connectivity (PostgreSQL ping)
• Application startup complete

Environment Variables¶

Environment variables are managed in the Railway dashboard under the service's "Variables" tab. Never commit secrets to the repository. See the configuration reference for the full list.

Manual Deploy via Railway CLI¶

If you need to deploy without pushing to main (e.g., for testing a branch):

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

# Login
railway login

# Link to the project (one-time)
railway link

# Deploy the current directory
railway up

# View logs
railway logs

Rollback¶

To roll back to a previous deployment:

1. Open the Railway dashboard.
2. Navigate to the service's "Deployments" tab.
3. Click on a previous successful deployment.
4. Click "Rollback to this deployment."

Alternatively, revert the commit on main and let auto-deploy handle it.

Frontend -- Vercel¶

The Curaway frontend is deployed on Vercel with automatic deploys on push to main.

Auto-Deploy¶

Vercel watches the frontend repository for pushes to main. Each push triggers:

1. npm install -- Install dependencies.
2. npm run build -- Build the Next.js application.
3. Deploy to the Vercel edge network.

Preview Deployments¶

Every pull request gets a unique preview URL (e.g., https://curaway-frontend-pr-42.vercel.app). This allows reviewers to test changes before merging.

Environment Variables¶

Frontend environment variables are managed in the Vercel dashboard under "Settings > Environment Variables." Variables prefixed with NEXT_PUBLIC_ are exposed to the browser; all others are server-side only.

Custom Domain¶

The production deployment is accessible at https://app.curaway.ai via a CNAME record pointing to Vercel's edge.

Documentation -- GitHub Pages¶

The MkDocs documentation site is deployed to GitHub Pages via a GitHub Actions workflow.

Workflow: .github/workflows/docs.yml¶

The workflow triggers on pushes to main when files in the docs/ directory change:

name: Deploy Docs
on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install MkDocs
        run: pip install mkdocs-material mkdocs-swagger-ui-tag

      - name: Build and Deploy
        run: mkdocs gh-deploy --force

Manual Docs Deploy¶

To deploy documentation manually (e.g., after a hotfix):

pip install mkdocs-material mkdocs-swagger-ui-tag
mkdocs gh-deploy --force

Local Docs Preview¶

To preview the documentation site locally before pushing:

mkdocs serve

The site will be available at http://localhost:8000.

The gsync Alias¶

The gsync alias is a convenience command for syncing your local main branch with the remote. It is defined as:

alias gsync='git fetch origin && git reset --hard origin/main'

When to Use gsync¶

• After a deployment when you want your local main to match production.
• When git pull reports "Already up to date" but you know there are remote changes (this can happen when the local branch has diverged). See the troubleshooting runbook for details.

Setup¶

Add to your shell profile (~/.zshrc or ~/.bashrc):

alias gsync='git fetch origin && git reset --hard origin/main'

Deployment Checklist¶

Before deploying to production, verify:

• [ ] All tests pass (pytest for backend, npm test for frontend)
• [ ] Linting passes (ruff check . for backend, npm run lint for frontend)
• [ ] Database migrations are committed and tested (alembic upgrade head)
• [ ] Environment variables are set in Railway/Vercel for any new config
• [ ] Feature flags are configured in Flagsmith for any new features
• [ ] Documentation is updated for any API changes

Monitoring After Deploy¶

After a deployment reaches production:

1. Check Railway deployment logs for startup errors.
2. Verify the health check: curl https://services.curaway.ai/ready
3. Spot-check a key endpoint: curl -H "X-Tenant-ID: tenant-apollo-001" https://services.curaway.ai/api/v1/providers/
4. Monitor Langfuse for LLM tracing anomalies.
5. Check Flagsmith for any flag evaluation errors.