Spaces:
Running
Running
| # 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 | |
| ```bash | |
| 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`. | |