# Configuration and bootstrap environment

**One root .env** — copy from .env.example. Do **not** create apps/api/.env. Product secrets belong in the dashboard after login.

## Required bootstrap (names only — never paste real secrets)

| Variable | Purpose |
|----------|---------|
| DATABASE_URL | Postgres (local compose often host port 5433) |
| APP_ENV | development / staging / production |
| HTTP_ADDR | API listen (dev commonly :28471) |
| WEB_ORIGIN | Browser origin for CORS/cookies (:28472 local) |
| PUBLIC_API_URL | Public API origin for the web app |
| SESSION_SECURE | Cookie Secure; must be true in production |
| TOKEN_SIGNING_SECRET | Session/invite HMAC (openssl rand -hex 32) |
| APP_ENCRYPTION_KEY | At-rest encryption for BYOK/store secrets (preferred) |

## Optional bootstrap (safe to override)

TRUSTED_PROXIES (comma CIDRs/IPs of hop-1 reverse proxies only — enables TrustedRealIP rewrite of RemoteAddr for rate limits; empty = ignore X-Forwarded-For), RATE_LIMIT_REPLICAS (optional; divides HTTP middleware RPM caps when N>1 — still per-process; edge still required for hard global RPM; does not affect lockout/StartLimiter/AI/email), SESSION_COOKIE_NAME, CSRF_COOKIE_NAME, PUBLIC_CSRF_COOKIE_NAME, SESSION_IDLE_HOURS, UPLOAD_DIR, MAINTENANCE_MODE, READ_ONLY_MODE, CREDENTIALS_ENCRYPTION_KEY (legacy alias for APP_ENCRYPTION_KEY), DOTENV_PATH.

## Prefer dashboard (not root .env)

| Area | UI |
|------|-----|
| Stripe, EPREL kill-switch, feed private-URL allowlist | /admin/settings |
| Tenant AI | /integrations/ai |
| Marketing email | /integrations/email |
| Stores | /stores |

Optional process-env fallbacks still accepted by some resolvers (OPENAI_*, SMTP_*, EPREL_*, FEED_URL_PRIVATE_ALLOWLIST) — prefer UI for day-to-day.

Production fail-closed (APP_ENV=production): SESSION_SECURE=true, https WEB_ORIGIN, APP_ENCRYPTION_KEY, TOKEN_SIGNING_SECRET, STRIPE_MOCK=false.

Never commit real secrets. Diagnostics exposes **presence flags** only (*_set), never values.

Source: root .env.example, README.md Environment section, docs/ops-runtime.md.