Skip to main content

Environment Configuration

Environment Configuration

Project: {{PROJECT_NAME}} Version: {{VERSION}} Date: {{DATE}} Author: {{AUTHOR}} Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}}

Document History

Version Date Author Changes
0.1 {{DATE}} {{AUTHOR}} Initial draft

1. Environment Overview

Environment Purpose URL Access Managed By
Local Developer workstation localhost Developer Individual
Dev Integration, daily builds dev.{{DOMAIN}} Team + CI Platform team
Staging Pre-production validation staging.{{DOMAIN}} Team + QA + PM Platform team
Production Live system {{DOMAIN}} Ops only Platform team
Preview Feature branch review {{BRANCH}}.preview.{{DOMAIN}} Team + Stakeholders CI/CD

2. Per-Environment Configuration

2.1 Development Environment

Parameter Value Notes
Log level DEBUG Verbose logging for development
Database dev-db.{{INTERNAL_DOMAIN}} Shared dev DB, refreshed weekly
Cache dev-redis.{{INTERNAL_DOMAIN}} Shared Redis, no persistence
Email Mailtrap / fake SMTP Emails not delivered to real recipients
Payments Sandbox / test mode No real transactions
Feature flags All enabled Developers can test unreleased features
Debug tools Enabled Profiler, debug toolbar, etc.
Rate limiting Disabled Developer convenience
Auto-migrations Enabled Runs on startup

2.2 Staging Environment

Parameter Value Notes
Log level INFO Same as production
Database staging-db.{{INTERNAL_DOMAIN}} Isolated staging DB, production-scale
Cache staging-redis.{{INTERNAL_DOMAIN}} Dedicated Redis
Email staging@{{DOMAIN}} Sends to internal test inboxes only
Payments Sandbox / test mode No real transactions
Feature flags Mirrors production + staged features
Debug tools Disabled Must match production behavior
Rate limiting Enabled Same limits as production
Data refresh Weekly from production (anonymized) See data refresh runbook

Intentional staging/production differences:

  • Email delivery: internal only (not real users)
  • Payment: sandbox (not real transactions)
  • Data: anonymized copies (not real PII)

2.3 Production Environment

Parameter Value Notes
Log level WARN Errors and warnings only
Database {{PROD_DB_HOST}} See secrets manager
Cache {{PROD_REDIS_HOST}} Clustered Redis
Email {{EMAIL_PROVIDER}} Real delivery via SES/Sendgrid/etc.
Payments Live mode Real transactions
Feature flags Conservative — tested features only New features behind flags
Debug tools Disabled Security requirement
Rate limiting Enabled See rate limit table
HSTS Enabled (1 year, includeSubDomains)
CSP Strict See security headers config

2.4 Preview / Feature Environments

Trigger: Pull request opened against main / develop Lifetime: Active while PR is open; destroyed on PR close URL Pattern: {{BRANCH_SLUG}}.preview.{{DOMAIN}} Database: Ephemeral copy (seeded from fixture data, not production) Teardown: Automated — triggered by PR close webhook

Parameter Value
Log level DEBUG
Email Fake SMTP / preview inbox
Payments Sandbox
Feature flags Branch-specific flags enabled

3. Environment Variables Reference

Variable Description Required Default Sensitive Environments
NODE_ENV Runtime environment Yes development No All
PORT HTTP server port Yes 3000 No All
DATABASE_URL PostgreSQL connection string Yes — Yes All
REDIS_URL Redis connection string Yes redis://localhost:6379 Yes All
JWT_SECRET JWT signing key Yes — Yes All
JWT_EXPIRY Token expiry duration Yes 1h No All
SMTP_HOST SMTP server hostname Yes — No All
SMTP_USER SMTP username Yes — Yes All
SMTP_PASS SMTP password Yes — Yes All
S3_BUCKET Object storage bucket name Yes — No All
AWS_REGION Cloud region Yes eu-west-1 No All
SENTRY_DSN Error tracking DSN No — Yes Staging, Prod
STRIPE_KEY Payment API key Yes (if payments) — Yes All
LOG_LEVEL Logging verbosity No info No All
RATE_LIMIT_WINDOW Rate limit window (ms) No 60000 No All
RATE_LIMIT_MAX Max requests per window No 100 No All
FEATURE_FLAG_KEY Feature flag SDK key No — Yes All

Rules:

  • Sensitive variables MUST be sourced from {{SECRET_STORE}} in staging and production
  • Never commit sensitive values to source control
  • Use .env.example with placeholder values for developer onboarding
  • Rotate all secrets on team member offboarding

4. Secrets Management

4.1 Secret Storage Solution

Solution: {{SECRET_TOOL}}

Environment Secret Store Access Method
Local .env file (never committed) Developer managed
Dev {{DEV_SECRET_STORE}} CI/CD service account
Staging {{STG_SECRET_STORE}} IAM role / service account
Production {{PROD_SECRET_STORE}} IAM role / service account

4.2 Secret Rotation Schedule

Secret Type Rotation Schedule Automated Owner
Database passwords 90 days {{AUTOMATED}} Platform team
API keys (internal) 365 days No Service owner
API keys (third-party) On compromise No Dev lead
JWT signing keys 365 days No Platform team
TLS certificates 60 days before expiry {{AUTOMATED}} Platform team

4.3 Access Controls

Role Dev Secrets Staging Secrets Production Secrets
Developer Read/Write Read No access
DevOps Read/Write Read/Write Read/Write
CI/CD (build) Read Read No access
CI/CD (deploy) No access Read Read
Application runtime Read (scoped) Read (scoped) Read (scoped)

5. Feature Flags Per Environment

Tool: {{FF_TOOL}}

Flag Dev Staging Production Notes
feature-new-checkout On On Off Waiting for QA sign-off
feature-dark-mode On On Off Rollout planned {{DATE}}
kill-switch-payments Off Off Off Emergency disable only
maintenance-mode Off Off Off Emergency only

6. Database Configuration Per Environment

Parameter Local Dev Staging Production
Host localhost {{DEV_DB}} {{STG_DB}} {{PROD_DB}}
Port 5432 5432 5432 5432
Database name {{APP}}_dev {{APP}}_dev {{APP}}_staging {{APP}}_prod
Max connections 10 25 50 {{PROD_CONNS}}
SSL required No No Yes Yes
Connection pool No No Yes ({{POOL}}) Yes ({{POOL}})
Read replica No No No Yes
Backup No Daily Daily {{BACKUP_FREQ}}

7. External Service Configuration Per Environment

Service Dev Staging Production Notes
Email (SMTP) Mailtrap Mailtrap SendGrid / SES
Payments Stripe test Stripe test Stripe live Different API keys
SMS Twilio test Twilio test Twilio live
Analytics Disabled Staging property Production property
Error tracking Disabled Sentry dev project Sentry prod project
Maps No key / free tier Paid key Paid key

8. Environment Provisioning Process

  1. Infrastructure provisioning: terraform apply -var-file=envs/{{ENV}}.tfvars
  2. Secret provisioning: bash scripts/provision-secrets.sh {{ENV}}
  3. Database provisioning: bash scripts/create-db.sh {{ENV}}
  4. DNS configuration: Update DNS records per deployment-architecture.md
  5. TLS certificates: Auto-provisioned via {{CERT_TOOL}}
  6. Initial deployment: Trigger CI/CD for {{ENV}} target
  7. Verification: Run smoke tests against new environment

Estimated time: {{PROVISION_TIME}} minutes Runbook: {{PROVISION_RUNBOOK_LINK}}

9. Environment Teardown Process

  1. Verify no active users or critical processes
  2. Export any required data / logs
  3. Remove DNS records
  4. Revoke TLS certificates
  5. terraform destroy -var-file=envs/{{ENV}}.tfvars
  6. Purge secrets from secret store
  7. Archive environment configuration to {{ARCHIVE_LOCATION}}
  8. Update this document to remove the environment entry

10. Parity Policy (Staging ↔ Production Drift)

Goal: Staging should be functionally identical to production at all times.

Area Policy
Application version Staging is always ahead by ≤ 1 release
Infrastructure spec Same instance types and topology
Database engine & version Must match exactly
OS & runtime versions Must match exactly
Third-party dependencies Same versions (except external service mode)
Network topology Same (except size)
Security controls Same

Drift detection: {{DRIFT_DETECTION}} Drift resolution owner: Platform team

Approval

Role Name Date Signature
Author
Reviewer
Approver
Back to top