​

Production Deployment Checklist

​

Architecture

GitHub (main branch)
  → GitHub Actions CI/CD (.github/workflows/deploy.yml)
    → Railway.app (split architecture)
      ├── syntropy-portal  (frontend-only, PORT=3000)
      └── syntropy-api     (backend-only, PORT=8000)

External Services:
  ├── Clerk          (auth, syntropyhealth.bio)
  ├── Supabase       (PostgreSQL, prod instance)
  ├── Zilliz Cloud   (vector DB, Milvus)
  ├── Stripe         (payments)
  ├── PostHog        (analytics)
  ├── Brevo          (transactional email)
  ├── OpenRouter     (LLM provider)
  └── Shopify        (protocol marketplace)

​

Branch → Environment Mapping

​

Pre-Deploy Checklist

​

1. DNS Records (Cloudflare — syntropyhealth.bio)

​

Clerk Email (DKIM + SPF) — proxy OFF required

​

Clerk Account Portal — proxy OFF for Clerk verification

Note: The Frontend API uses proxy mode (see below) — no clerk.* CNAME is needed. All Clerk JS requests route through https://syntropyhealth.bio/__clerk.

​

2. Clerk Dashboard Setup (clerk.com)

​

2a. Domain & Proxy Configuration

1. Go to Clerk Dashboard → Domains
2. In the Frontend API section, click Set proxy configuration
3. Enter the proxy URL: https://syntropyhealth.bio/__clerk
4. Save — Clerk will verify the proxy is reachable (must be deployed first)

Browser → https://syntropyhealth.bio/__clerk/* (your domain, Cloudflare proxy ON)
  → FastAPI route (clerk_proxy.py) adds required headers:
      Clerk-Proxy-Url: https://syntropyhealth.bio/__clerk
      Clerk-Secret-Key: sk_live_...
      X-Forwarded-For: <client IP>
  → Forwards to https://clerk.syntropyhealth.bio/* (Clerk's FAPI)
  → Response returned to browser

• Proxy route: syntropy_journals/app/api/routes/clerk_proxy.py
• Provider config: page_wrapper.py passes proxy_url="/__clerk" to clerk_provider()
• Activated by: CLERK_PROXY_ENABLED=true env var (prod only)

​

2b. Path & Redirect Configuration

​

2c. Social Login (OAuth)

• Google OAuth configured (minimum)
• OAuth callback URLs will route through the /__clerk proxy automatically
• Email verification enabled (after DKIM records propagate)

​

2d. Deployment Order for Proxy

1. First deploy the app with CLERK_PROXY_ENABLED=true (Railway)
2. Then set the proxy URL in Clerk Dashboard
3. Clerk verifies https://syntropyhealth.bio/__clerk is reachable
4. Once verified, all Clerk JS requests route through your domain

​

3. GitHub Actions Secrets

​

4. Railway Environment Variables

• APP_ENV=PROD
• FRONTEND_DEPLOY_URL=https://syntropy-portal-production.up.railway.app
• REFLEX_DEPLOY_URL=https://syntropy-portal-production.up.railway.app
• REFLEX_ACCESS_TOKEN=<from envs/prod>

• CLERK_PUBLISHABLE_KEY=pk_live_*
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_*
• CLERK_SECRET_KEY=sk_live_*
• CLERK_AUTHORIZED_DOMAINS=https://syntropyhealth.bio
• CLERK_PROXY_ENABLED=true — routes Frontend API through /__clerk
• CLERK_PROXY_URL=/__clerk — (optional, this is the default)

• REFLEX_DB_URL=<Supabase prod pooler URL>

• VECTOR_DB_TYPE=zilliz
• ZILLIZ_CLOUD_URI=<from envs/base>
• ZILLIZ_CLOUD_API_KEY=<from envs/base>

• OPENROUTER_API_KEY=<from envs/base>
• OPENAI_API_KEY=<from envs/base>

• STRIPE_SECRET_KEY=<live key>
• STRIPE_PUBLISHABLE_KEY=<live key>
• STRIPE_WEBHOOK_SECRET=<live webhook signing secret>
• BASE_URL=https://syntropyhealth.bio

• POSTHOG_PROJECT_API_KEY=<from envs/base>
• POSTHOG_HOST=https://us.i.posthog.com

• REDIS_URL=rediss://...@open-dragon-87263.upstash.io:6379 — Upstash Redis (TLS)
• Enables multi-worker state sharing and session persistence
• Without this, Reflex uses disk-based state (single instance only)
• Must use Upstash or a Redis with full ACL permissions (set/get/config/subscribe)

• BREVO_API_KEY=<from envs/base>

​

5. Stripe Setup

• Stripe account in live mode
• Products and prices created matching app subscription tiers
• Webhook endpoint configured: https://syntropyhealth.bio/api/stripe/webhook
• Webhook events subscribed: checkout.session.completed, customer.subscription.*, invoice.*
• Webhook signing secret saved to STRIPE_WEBHOOK_SECRET

​

6. PostHog Setup

• Project created for production
• POSTHOG_PROJECT_API_KEY is the write-only project API key
• POSTHOG_HOST set to https://us.i.posthog.com

​

7. Database

• Supabase prod instance accessible
• Connection string uses pooler URL (port 6543)
• Alembic migrations up to date: uv run alembic upgrade head
• Catalog seeded: uv run python -m syntropy_journals.app.scripts.seed_data

​

Deploy Procedure

# 1. Ensure test branch is green
git checkout test
make test

# 2. Merge test → main
git checkout main
git merge test

# 3. Push to trigger CI/CD
git push origin main
# GitHub Actions: lint → unit tests → integration tests → Docker build → Railway deploy

# 4. Monitor deploy
gh run watch     # watch CI
# Railway dashboard → check service health

# 5. Verify
curl -s https://syntropy-portal-production.up.railway.app/ | head -5

​

Rollback

# Railway dashboard → Deployments → click previous deployment → Redeploy
# Or via Railway CLI:
railway service rollback

​

Env File Reference