# 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`.