Skip to content

Deployment Guide

This guide covers deploying the QGTM.AI platform to production. For the full step-by-step runbook, see Deploy Runbook.

Architecture Overview

                    ┌──────────────┐
                    │  Cloudflare  │
                    │  (DNS + CDN) │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴────┐ ┌────┴─────┐
        │  Web App   │ │  API   │ │  Docs    │
        │ (Next.js)  │ │(FastAPI│ │ (MkDocs) │
        │ CF Pages   │ │ Fly.io)│ │ CF Pages │
        └────────────┘ └───┬────┘ └──────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴────┐ ┌────┴─────┐
        │ PostgreSQL │ │ Redis  │ │ ArcticDB │
        │  (Neon)    │ │(Upstash│ │ (S3)     │
        └────────────┘ └────────┘ └──────────┘

Environments

Environment Purpose Branch
dev Local development any
staging Pre-production validation staging
production Live trading main (tagged releases)

Infrastructure Components

API Server (Fly.io)

flyctl launch --name qgtm-api
flyctl secrets set ALPACA_API_KEY=... ALPACA_SECRET_KEY=...
flyctl deploy

The API runs as a single Fly.io machine with autoscaling. Health checks hit /api/v1/health.

Database (Neon PostgreSQL)

  • Serverless PostgreSQL with branching for staging
  • Connection string goes in DATABASE_URL secret
  • Migrations run automatically on deploy via CI

Cache (Upstash Redis)

  • Serverless Redis for rate limiting, caching, and pub/sub
  • Connection string goes in REDIS_URL secret

Secrets (Doppler)

All secrets are managed in Doppler and injected at deploy time:

doppler run -- flyctl deploy

Never commit secrets to the repo. Use .env.example as the template.

CI/CD Pipeline

The GitHub Actions pipeline runs on every push:

  1. Lint -- ruff, mypy, eslint
  2. Test -- pytest with coverage gate (80%+)
  3. Build -- Docker image, Next.js static export, MkDocs site
  4. Deploy -- auto-deploy to staging on staging branch, manual promotion to production

Deployment Checklist

Before deploying to production:

  • [ ] All tests pass in CI
  • [ ] No critical/high security vulnerabilities
  • [ ] Database migrations reviewed and tested
  • [ ] Feature flags configured for gradual rollout
  • [ ] Kill switch tested and accessible
  • [ ] Monitoring dashboards verified
  • [ ] Rollback plan documented

Monitoring

System Tool Dashboard
API metrics Prometheus + Grafana /grafana
Error tracking Sentry sentry.io
Uptime Better Uptime status.qgtm.ai
Logs Fly.io built-in flyctl logs

Rollback

If a deployment causes issues:

# Immediate rollback to previous release
flyctl releases list
flyctl deploy --image registry.fly.io/qgtm-api:sha-PREVIOUS

# Or scale to zero and investigate
flyctl scale count 0

For database rollback, see Incident Response Runbook.

Docs Deployment

The documentation site (this site) deploys to Cloudflare Pages:

.venv/bin/python -m mkdocs build
# Output is in site/ -- deploy to CF Pages