Document: 25-environment-management.md
Version: 1.0.0

Purpose

This document defines the environment management strategy used across all Rundown projects.

Environments provide isolated spaces for development, testing, staging, and production. A consistent environment strategy reduces deployment risk, simplifies debugging, and ensures that applications behave predictably throughout their lifecycle.

Environment Philosophy

Applications should behave consistently across every environment.

Code should remain the same.

Only configuration should change.

Environment-specific behaviour should be controlled through configuration rather than conditional application logic.

Standard Environments

Every Rundown project should support the following environments:

Development

↓

Staging

↓

Production

Additional environments may be introduced for enterprise projects when justified.

Development

Purpose:

Daily development.

Characteristics:

• Local machine

• Debugging enabled

• Development database

• Mock services where appropriate

• Rapid iteration

Development should prioritize developer productivity.

Staging

Purpose:

Final validation before production deployment.

Characteristics:

• Mirrors production architecture

• Uses production-like configuration

• Accessible to internal teams and client stakeholders where appropriate

• Supports user acceptance testing (UAT)

Staging should be as close to production as possible.

Production

Purpose:

Serve real users.

Characteristics:

• Optimized builds

• Production credentials

• Monitoring enabled

• HTTPS enforced

• Performance optimized

• Backups enabled

Production should remain stable and predictable.

Responsibilities

Environment management owns:

• Environment separation

• Configuration

• Secrets

• Deployment targets

• Environment-specific services

Non-Responsibilities

Environment management should not own:

• Business logic

• Feature implementation

• Application architecture

• Content modelling

Applications should never behave differently because of business logic tied to an environment.

Configuration

Configuration should be stored outside the application source code.

Typical examples include:

• Database credentials

• API keys

• Email provider settings

• Storage credentials

• Analytics identifiers

Configuration should never be hardcoded.

Environment Variables

Every project should provide:

.env.example

This file should document all required variables without exposing sensitive values.

Sensitive credentials must never be committed to version control.

Feature Flags

Feature flags may be used when introducing incomplete or experimental functionality.

Feature flags should:

• Be temporary

• Be documented

• Be removed after rollout

Avoid long-lived feature flags that increase application complexity.

Database Strategy

Each environment should have its own database.

Development data must never be shared with production.

Production databases should never be modified for testing purposes.

Media Strategy

Each environment should have isolated media storage.

Development uploads should not appear in production.

Production assets should remain protected from accidental modification.

Secrets Management

Secrets should:

• Be environment-specific.

• Be securely stored.

• Rotate periodically where appropriate.

• Never appear in source control.

Access to production secrets should be restricted to authorized personnel.

Promotion Strategy

Code should move through environments in sequence:

Development

↓

Staging

↓

Production

Skipping environments should only occur in exceptional circumstances.

Environment Parity

Development and staging should closely resemble production.

Differences should be limited to:

• Credentials

• Domains

• External service endpoints

• Logging verbosity

Maintaining parity reduces deployment surprises.

Engineering Decision

Configuration Over Code

Status: Accepted

Decision

Environment-specific behaviour is managed through configuration rather than application logic.

Reasoning

This approach:

• Simplifies deployments.

• Reduces bugs.

• Improves consistency.

• Supports repeatable environments.

• Encourages clean application design.

Environment Checklist

Before deploying a new environment, verify:

• Configuration is complete.

• Secrets are securely stored.

• Separate database configured.

• Separate storage configured.

• HTTPS enabled where appropriate.

• Monitoring configured.

• Environment parity reviewed.

Summary

Environment management provides predictable and isolated execution environments throughout the application lifecycle.

By separating configuration from application code and maintaining strong parity between environments, Rundown projects reduce deployment risk while improving reliability and maintainability.

Related Documents

• 24-hosting-architecture.md

• 26-docker-architecture.md

• 27-deployment-workflow.md

Related ADRs

• ADR-003: Documentation Information Architecture