# 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

<!-- GUIDANCE: List all environments, their purposes, URLs, and access controls. -->

| 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

<!-- GUIDANCE: Document all dev-specific settings. Focus on what differs from defaults. -->

| 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

<!-- GUIDANCE: Staging should mirror production as closely as possible. Document any intentional differences. -->

| 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

<!-- GUIDANCE: Document production-specific configuration. Be explicit about security settings. -->

| 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

<!-- GUIDANCE: Document ephemeral environments created per PR/branch. -->

**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

<!-- GUIDANCE: Document ALL environment variables. Mark sensitive ones — these must come from secrets manager, not .env files in production. -->

| 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 |

<!-- TODO: Add all project-specific environment variables -->

**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

<!-- GUIDANCE: Document where secrets are stored and how they are accessed. -->

**Solution:** {{SECRET_TOOL}} <!-- AWS Secrets Manager / HashiCorp Vault / Azure Key Vault / 1Password Secrets Automation -->

| 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

<!-- GUIDANCE: Document who can read/write secrets in each environment. -->

| 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

<!-- GUIDANCE: Document feature flag defaults per environment and who controls them. -->

**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 |

<!-- TODO: Add all current feature flags -->

---

## 6. Database Configuration Per Environment

<!-- GUIDANCE: Document database-specific settings 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

<!-- GUIDANCE: Document all third-party integrations and their environment-specific configurations. -->

| 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

<!-- GUIDANCE: Document how to spin up a new environment (e.g., new staging, new preview). -->

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](./deployment-architecture.md)
5. **TLS certificates:** Auto-provisioned via {{CERT_TOOL}} <!-- cert-manager / ACM / Let's Encrypt -->
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

<!-- GUIDANCE: Document safe teardown procedure, especially for environments with data. -->

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)

<!-- GUIDANCE: Define acceptable and unacceptable drift between staging and production. -->

**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}} <!-- Automated check weekly / Manual review monthly -->
**Drift resolution owner:** Platform team

---

## Related Documents

- [Deployment Architecture](./deployment-architecture.md)
- [Infrastructure as Code](./infrastructure-as-code.md)
- [CI/CD Pipeline](./cicd-pipeline.md)
- [Local Development Setup](../DEVELOPER-EXPERIENCE/local-development-setup.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |