From 5c9d6aea8237b73d25357d76e2cebcf8065d9d86 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 1 Apr 2026 04:44:03 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20document=20Railway=20=E2=86=92=20Dopple?= =?UTF-8?q?r=20=E2=86=92=20local=20dev=20env=20var=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Future agents need to know that Railway is the source of truth for deployed env vars, Doppler syncs from Railway for local dev access, and new variables should be added via Railway CLI first. https://claude.ai/code/session_014Pzbze1fvmyaNMfWt4AFxG --- CLAUDE.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3640f033..f2a1fb72 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,9 +107,33 @@ Cursor does not load this file automatically. Keep `.cursor/rules/project-contex ### Environment Variables -- Local dev: `.env.local` (gitignored). -- Deployed: Railway service environment variables. +**Flow: Railway → Doppler → Local Dev** + +- **Railway** is the source of truth for all deployed environment variables (prod and staging). +- **Doppler** syncs from Railway. Each app has a Doppler project that mirrors the Railway service config. +- **Local dev** pulls from Doppler via `pnpm fetch-secrets`, which downloads into `.env` / `.env.local` (gitignored). + +Doppler projects: + +| App | Doppler Project | +|---|---| +| `apps/cms` | `forge-cms` | +| `apps/web` | `forge-web` | +| `apps/mobile` | `forge-mobile` | +| `apps/manager` | `forge-manager` | + +**Adding new environment variables:** + +1. Add to Railway first (the source of truth) using the Railway CLI or dashboard. +2. Doppler syncs automatically — the variable becomes available in the matching Doppler project. +3. Developers pull locally with `pnpm fetch-secrets` when they need it. +4. Non-secret config (e.g. cron schedules) with sensible defaults should use `process.env.VAR ?? "default"` so local dev works without fetching. + +**Rules:** + - Never hardcode secrets. Never commit `.env` files. +- Use Railway CLI (`railway variables set VAR=value`) to add new variables in deployed environments. +- Only add variables to Doppler directly if they are local-dev-only and not needed in deployment. ## Roadmap