Engineering Design
Environment & Secrets

Environment & Secrets Management

Rules

  • Never commit .env files — .gitignore covers all .env* patterns
  • NEXT_PUBLIC_ prefix exposes variables to the browser — never put secrets here
  • All secrets stored in 1Password, shared via Fly.io secrets (backend) and Vercel env vars (frontend)
  • Rotate JWT_SECRET and COOKIE_SECRET before Phase 2 public launch
  • Stripe: separate keys for development, staging, and production environments

Backend Secrets (Fly.io)

VariablePurposeRotate when
DATABASE_URLSupabase connection stringOn DB credential change
JWT_SECRETJWT signingBefore Phase 2 launch
COOKIE_SECRETCookie signingBefore Phase 2 launch
STRIPE_SECRET_KEYStripe server-sideOn team member departure
STRIPE_WEBHOOK_SECRETWebhook HMACOn webhook endpoint change
RESEND_API_KEYEmail sendingAnnually or on breach
R2_ACCESS_KEY_ID / SECRETCloudflare R2Annually or on breach

Frontend Env Vars (Vercel)

VariablePublic?Value
NEXT_PUBLIC_MEDUSA_BACKEND_URLYeshttps://api.shop.vespertene.com
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEYYesFrom Medusa admin → Settings → API Keys
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYYespk_live_... (never sk_live_)
NEXT_PUBLIC_STORE_URLYeshttps://shop.vespertene.com
Architecture Decision RecordsCode Review Checklist