Integration Deployment

Integration & Deployment

Principles That Apply

For full rationale on any principle: .claude/skills/architecture-principles/reference.md

Platform: Fly.io

Both apps deploy as Docker containers to Fly.io in the iad (US East) region.

Both use auto_stop_machines = 'stop' and min_machines_running = 0 for cost control.

Quick Reference

Deploy commands

# Automatic: push to main triggers .github/workflows/fly-deploy.yml
# Both apps deploy in parallel via GitHub Actions

# Manual deploy from project root:
flyctl deploy --config chatServer/fly.toml --dockerfile chatServer/Dockerfile
flyctl deploy --config webApp/fly.toml --dockerfile webApp/Dockerfile

Set secrets

# chatServer secrets
flyctl secrets set SUPABASE_URL="..." SUPABASE_SERVICE_ROLE_KEY="..." ANTHROPIC_API_KEY="..." -a clarity-chatserver

# webApp secrets (used at build time)
flyctl secrets set VITE_SUPABASE_URL="..." VITE_SUPABASE_ANON_KEY="..." VITE_API_BASE_URL="https://clarity-chatserver.fly.dev" -a clarity-webapp

Check status

flyctl status -a clarity-chatserver
flyctl status -a clarity-webapp
flyctl logs -a clarity-chatserver
flyctl logs -a clarity-webapp

Pre-Deploy Checklist

• All tests pass (pytest + cd webApp && pnpm test)
• Linting clean (ruff check + pnpm lint)
• No .env files in Docker context (check .dockerignore)
• Fly secrets set for any new env vars (chatServer AND webApp if applicable)
• GitHub repo secrets set if env var is used in CI/CD workflows (e.g., --build-arg)
• New Python deps added to BOTH requirements.txt (root) AND chatServer/requirements.txt
• Database migrations applied to production Supabase
• CORS origins in chatServer/main.py include the production frontend URL
• All frontend API hooks use VITE_API_BASE_URL (not VITE_API_URL) — only VITE_API_BASE_URL is passed at build time

Environment Variables

chatServer (runtime secrets on Fly)

webApp (build-time ARGs via GitHub secrets + --build-arg in CI)

webApp vars are injected at build time via Docker ARG in .github/workflows/fly-deploy.yml. These are GitHub repo secrets (not Fly secrets). They are NOT truly secret — they're baked into the JS bundle.

Key Gotchas

1. Fly deploy from repo root — fly.toml lives in chatServer/ and webApp/. Deploy with flyctl deploy --config <app>/fly.toml --dockerfile <app>/Dockerfile.
2. CORS — Both frontend ports must be in settings.cors_origins in chatServer/main.py.
3. Telegram: one bot = one webhook URL — Running locally with prod bot token steals the webhook from production. Use separate bot tokens per environment.

Detailed Reference

For Dockerfiles, fly.toml configs, API routing (dev proxy vs production), Supabase environment management, and CI/CD plans, see reference.md.