docs/deployment.md

Deployment Guide

This guide defines a minimal production deployment baseline.

1) Required environment variables

• API_KEYS
• API_KEY_TENANT_CONFIG
• PROMOTION_GATE_POLICY
• RUNTIME_STATE_BACKEND (file or postgres)
• SESSION_TTL_SECONDS (auth session TTL, minimum 300, default 86400)
• SESSION_RENEW_WINDOW_SECONDS (sliding renew window in seconds, minimum 60, default 1800)
• SESSION_COOKIE_SECURE (true to add Secure flag on session cookie; defaults to true in production)
• CHECKOUT_RATE_LIMIT_WINDOW_SECONDS (window length for checkout creation attempts, default 300)
• CHECKOUT_RATE_LIMIT_MAX_PER_WINDOW (max checkout create attempts per tenant in window, default 5)
• FREE_SIGNUP_RATE_LIMIT_WINDOW_SECONDS (window length for free-signup attempts per source IP, default 3600)
• FREE_SIGNUP_RATE_LIMIT_MAX_PER_WINDOW (max free-signup attempts per source IP in window, default 3)
• DATABASE_URL (required when backend is postgres)
• COST_AWARE_DECISION_ENABLED (true to let /api/v1/optimize apply decision pre-gate; default false)
• BILLING_OVERAGE_CAP_USD (monthly pay-as-you-go cap in USD for over-quota usage; default 5, set <=0 to disable)
• BILLING_RECOVERY_MIN_STARTED_SAMPLES (minimum recovery-started sample size before readiness success-rate blockers are enforced; default 5)
• BILLING_RECOVERY_GO_MIN_SUCCESS_RATE_PCT (GO target for recovery success rate; default 40)
• BILLING_RECOVERY_NO_GO_CRITICAL_SUCCESS_RATE_PCT (critical NO-GO threshold when payment-failure risk exists; default 25)
• FREE_PLAN_DAILY_QUOTA_USD (default daily quota for auto-created free tenants, in USD; default 1)
• PRO_PLAN_EARLY_BIRD_PRICE_USD (default 9)
• PRO_PLAN_STANDARD_PRICE_USD (default 15)
• PRO_PLAN_EARLY_BIRD_START_AT (ISO datetime, inclusive)
• PRO_PLAN_EARLY_BIRD_END_AT (ISO datetime, exclusive)
• STRIPE_PRICE_PRO_EARLY_BIRD_MONTHLY (Stripe Price ID for early-bird monthly subscription)
• STRIPE_PRICE_PRO_STANDARD_MONTHLY (Stripe Price ID for standard monthly subscription)
• STRIPE_SECRET_KEY (required for POST /api/v1/billing/checkout/session in non-test environments)
• PRO_PLAN_GRANDFATHERING_ENABLED (true for plan A: existing subscribers keep original price ID)
• REFERRAL_WEBHOOK_SECRET (HMAC secret for /api/v1/referral/webhook signature verification)
• REFERRAL_RISK_ALERT_THRESHOLD (0-100 score threshold for referral risk warning alerts; default 60)
• REFERRAL_RISK_WEIGHT_IGNORED_RATE (default 0.4)
• REFERRAL_RISK_WEIGHT_SELF_REFERRAL (default 15)
• REFERRAL_RISK_WEIGHT_DUPLICATE_REFEREE (default 10)
• REFERRAL_RISK_WEIGHT_REWARD_REVERSED (default 8)

Operational note:

• Referral risk APIs now support time range and aggregation controls:
  • GET /api/v1/referral/risk-trend?days=30&granularity=day
  • GET /api/v1/referral/risk-trend?from=<iso>&to=<iso>&granularity=week
  • GET /api/v1/referral/high-risk-summary?... for high-risk bucket summaries.

Optional but recommended:

• ALERT_WEBHOOK_URL
• ALERT_WEBHOOK_RETRIES
• ALERT_WEBHOOK_TIMEOUT_MS

2) Build and run

npm install
npm run build
NODE_ENV=production START_SERVER=true npm run start

Service default bind:

• Host: 0.0.0.0
• Port: 3000

3) Reverse proxy expectations

• Forward x-forwarded-for correctly.
• Keep health probe on GET /api/v1/health.
• Ensure request body size supports current limit (5mb).

4) First deployment checks

• GET /api/v1/health returns status=ok.
• GET /api/v1/metrics returns Prometheus text.
• GET /api/v1/ops/metrics is reachable with admin key.
• Trigger one test alert and verify webhook delivery or dead-letter behavior.

5) Runtime state strategy

• For single-node: file backend is acceptable for MVP.
• For multi-node/high-availability: prefer postgres backend.
• Backup/restore procedures should include runtime state store.

6) Security baseline

• Never expose API keys in frontend.
• Rotate keys on suspicious traffic.
• Keep admin keys separate from operator keys.
• Restrict /api/v1/ops/* and dead-letter replay endpoints to admin role.
• Browser checkout flow should use session auth endpoints:
  • POST /api/v1/auth/session (create session via API key; server sets HttpOnly cookie)
  • GET /api/v1/auth/session (check login state)
  • DELETE /api/v1/auth/session (logout)

7) Google Cloud staging

• See docs/gcp-staging.md for Cloud Run staging deployment.
• Recommended script: scripts/deploy-gcp-staging.sh.