Where They Live

There are exactly three homes for a config secret, one per environment, and they're deliberately different mechanisms. This page walks each one and the script that ties the deployed two together.

• Local dev → a .env.local file in the repo root, which you create yourself and which git ignores.
• Staging → infra/staging/secrets.staging.yaml, synced into Railway.
• Production → infra/prod/secrets.prod.yaml, synced into Railway.

.env.local

When the app boots, NestJS's ConfigModule is told to load from .env.local.

ConfigModule.forRoot({
  isGlobal: true,
  load: [config],
  envFilePath: '.env.local',
}),

That populates process.env before the Zod schema validates it. (Sentry is wired even earlier — apps/server/src/instrument.ts calls dotenv.config({ path: '.env.local' }) at the very top of main.ts, before any module loads, so error reporting is live from the first line.) You build .env.local by hand, filling in every required key from the schema with values a teammate hands you out-of-band — never from a committed file, because there isn't one.

The secrets YAML

For deployed environments, every variable lives in a per-environment YAML file under infra/. Each file is a flat KEY: 'value' map, grouped by comment headers that mirror the inventory table.

# infra/prod/secrets.prod.yaml
# Railway environment variables for the Production environment.
# DO NOT commit to a public repo — this file contains real secrets.

# Database
DATABASE_URL: '<your-database-url>'

# Auth / JWT
JWT_SECRET_KEY: '<your-jwt-secret>'

# Microsoft
MICROSOFT_CLIENT_SECRET: '<your-microsoft-client-secret>'
MICROSOFT_WEBHOOK_SECRET: '<your-microsoft-webhook-secret>'

# API docs (HTTP Basic Auth protecting /docs in non-dev envs)
DOCS_USERNAME: '<your-docs-username>'
DOCS_PASSWORD: '<your-docs-password>'

One value is special: REDIS_URL is set to '${{ Redis.REDIS_URL }}' — a Railway reference variable, not a literal. Railway resolves it at deploy time to the private internal URL of the linked Redis service, so the real connection string is never written into the file at all. That's the ideal: a secret the platform injects so we never have to hold it.

The Railway sync

These YAML files are pushed to Railway by scripts/sync-railway-env.sh, which reads the env folder, finds the target services from infra/<env>/railway.yaml, and runs railway variable set for every key/value pair on every listed service.

# Collect KEY=VALUE pairs from secrets.<env>.yaml
while IFS= read -r line; do pairs+=("$line"); done \
  < <(yq 'to_entries | .[] | .key + "=" + (.value | tostring)' "$secrets_file")

# Push them to every service listed in railway.yaml, one deploy each
for service_id in $service_ids; do
  railway variable set "${pairs[@]}" \
    --service "$service_id" \
    --environment "$environment_id"
done

The railway.yaml next to each secrets file is the routing table — it names the project, the environment, and the service IDs (stable even if someone renames a service in the dashboard) that should receive the variables.

projectId: <project-id>
environmentId: <environment-id>
services:
  - id: <api-service-id>
    name: Naalya-API
  - id: <worker-service-id>
    name: Naalya-Worker

So the full picture for a deployed env: edit the secrets.*.yaml, run scripts/sync-railway-env.sh infra/prod (with RAILWAY_TOKEN exported), and the script commits one deploy per service with the new values live. There is no manual variable-by-variable clicking in the Railway UI.

Where to go next