Environment Management
Manage secrets safely across development, staging, and production — .env files, secrets injection, and environment parity
Skills taught: deployment.env-management, deployment.secrets, deployment.environment-parity, deployment.dotenv, deployment.secret-rotation
The environment variable problem
Every app has secrets: database passwords, API keys, JWT signing secrets, Stripe keys. The wrong approach is to hardcode them in source code (they end up in git history, visible to anyone with repo access). The right approach is environment variables — values injected into your app at runtime from outside the codebase. The challenge is managing these variables across multiple environments (dev, staging, production) without losing them, leaking them, or having them drift out of sync.
.env file conventions
# .env — local development secrets (NEVER commit this)
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
JWT_SECRET=dev-only-not-secure
STRIPE_SECRET_KEY=sk_test_...
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=...
# .env.example — template committed to git (no real values)
# Shows developers what variables are needed
DATABASE_URL=
REDIS_URL=
JWT_SECRET=
STRIPE_SECRET_KEY=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
# .gitignore — MUST include:
.env
.env.local
.env.*.local
# Never ignore .env.example — that one gets committed
# Loading .env in Node.js:
# Option 1: node --env-file=.env server.js (Node 20+, no package needed)
# Option 2: dotenv package
import 'dotenv/config'; // loads .env into process.env automatically
# Option 3: dotenv with path
import dotenv from 'dotenv';
dotenv.config({ path: '.env.local' });
Multiple environments
DEVELOPMENT (.env.local or .env):
Purpose: local development on your machine
Database: local PostgreSQL or Docker
Secrets: test/dev keys (sk_test_..., dummy values)
NEVER matches production exactly (and shouldn't)
STAGING (.env.staging or injected by platform):
Purpose: pre-production testing
Database: separate database (never share with production!)
Secrets: real API keys pointing to test environments
Matches production config structure but with test data
URL: staging.myapp.com
PRODUCTION (.env.production or platform secrets):
Purpose: live users
Database: production database
Secrets: live API keys (sk_live_...)
Should be impossible to accidentally run locally
KEY RULE: Never use production secrets in development.
If dev accidentally writes to the production database, that's catastrophic.
Environment parity means same code runs in each, but different config.
ENVIRONMENT PARITY (the 12-factor app principle):
✓ Same Docker image in staging and production
✓ Same database engine (use PostgreSQL in dev too, not SQLite)
✓ Same environment variable names
✗ Different codepaths for 'dev mode' (they'll diverge)
✗ Different dependencies (dev uses MySQL, prod uses PostgreSQL)
Secrets injection in CI/CD and production
# Store secrets in: GitHub repo → Settings → Secrets and variables → Actions
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build and push Docker image
run: |
docker build \
--build-arg NODE_ENV=production \
-t ghcr.io/myorg/myapp:${{ github.sha }} .
- name: Deploy to VPS
env:
# These come from GitHub Secrets — never logged
DATABASE_URL: ${{ secrets.PRODUCTION_DATABASE_URL }}
JWT_SECRET: ${{ secrets.JWT_SECRET }}
run: |
ssh deploy@${{ secrets.VPS_HOST }} << 'ENDSSH'
cd /home/deploy/myapp
docker compose pull
docker compose up -d
ENDSSH
# Note: Secrets are NEVER exposed in logs
# GitHub replaces secret values with *** in logs automatically
# Even if you accidentally 'echo $DATABASE_URL', logs show '***'
# On your VPS, secrets live in the .env file
# Loaded by Docker Compose via env_file or environment:
# /home/deploy/myapp/.env (permissions 600 — owner-only read)
chmod 600 /home/deploy/myapp/.env
# Or use Docker secrets (for Swarm mode):
docker secret create db_password - <<< 'supersecretpassword'
# In docker-compose.yml:
services:
app:
secrets:
- db_password
environment:
# Secret mounted at /run/secrets/db_password
# Read it in Node.js:
# const secret = fs.readFileSync('/run/secrets/db_password', 'utf8');
DB_PASSWORD_FILE: /run/secrets/db_password
secrets:
db_password:
external: true
# AWS Secrets Manager (for AWS deployments):
import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
const client = new SecretsManagerClient({ region: 'ap-south-1' });
const { SecretString } = await client.send(
new GetSecretValueCommand({ SecretId: 'myapp/production/database' })
);
const { password, username } = JSON.parse(SecretString!);
Warning: Never commit secrets to git — even 'just this once' or 'I'll remove it later'. Git history is permanent. Even if you remove the secret in the next commit, it's still in the history and visible to anyone who runs git log -p. If you accidentally commit a secret: rotate it immediately (generate a new key, revoke the old one), then remove it from history with git filter-repo. GitHub will also scan your pushes for known secret patterns and alert you — but rotating is still required.
Frequently Asked Questions
What tool should I use to manage team secrets?
For small teams: use your deployment platform's secret management (Vercel Env Vars, Railway Variables, GitHub Secrets). For larger teams: HashiCorp Vault (self-hosted, powerful), AWS Secrets Manager, or Doppler (developer-friendly SaaS secret manager that syncs to all your platforms). The key requirement: secrets should be changeable without editing code, and access should be audited.