Railway Deployment Guide
Deploy Relay on Railway for managed or staging environments using this checklist.
Prerequisites
- Railway project access (
relay-api,relay-worker) .envfiles exported from the control plane or generated locally- Clerk/Stripe credentials if enabling auth/billing
1. Install Dependencies
pip install -r requirements.txt
make install
Run migrations locally to verify schema currency:
python3 scripts/deployment/railway_migration_runner.py --dry-run
2. Provision Services
| Service | Purpose |
|---|---|
relay-api | FastAPI control plane |
relay-worker | Execution engine workers |
relay-queue | Redis/Upstash queue + cache |
relay-db | Postgres (Neon) metadata store |
Populate environment variables for each service (Railway dashboard → Variables). Copy from .env bundles and include Datadog credentials if available.
3. Deploy API Service
railway up --service relay-api
After the first deploy, apply migrations against the live database:
railway run --service relay-api python scripts/deployment/railway_migration_runner.py
4. Deploy Workers
railway up --service relay-worker --detach
Scale worker replicas based on queue depth and latency targets.
5. Configure Custom Domains
- Railway project → Settings → Domains
- Add
api.deployrelay.com(or equivalent) - Update DNS (CNAME or Cloudflare proxied record)
- Wait for SSL status
Issued
6. Observability
- Set
DATADOG_API_KEY,DATADOG_APP_KEY,DATADOG_SITE - Run
scripts/monitoring/api_telemetry_smoke.sh - Provision dashboards via
scripts/monitoring/setup_production_monitoring.py --component datadog
7. Billing & Marketplace (Optional)
- Configure Stripe secrets (
STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET) - Enable marketplace background jobs for entitlements/payouts
- Test billing webhooks following the Stripe webhook flow
8. Troubleshooting
| Issue | Resolution |
|---|---|
ModuleNotFoundError during build | Ensure pip install -r requirements.txt executed and lockfiles committed |
| Worker restarts repeatedly | Inspect logs for sandbox dependency failures |
| Queue backlog rising | Increase worker concurrency or investigate slow functions |
| Missing telemetry | Confirm Datadog env vars and agent connectivity |