Environments

Every project runs in more than one place. Documenting your environments removes ambiguity, reduces the chance of deploying to the wrong target, and makes onboarding significantly faster.

Standard Environments

Most projects use some combination of the following:

Environment	Purpose
Local	Individual developer machines. Each developer runs their own instance.
Development	A shared environment for integration testing after code is merged. Sometimes called "dev".
Staging	A production-like environment used for final verification before release. Traffic is not real.
Production	The live environment that serves real users.

Some teams also maintain a testing or QA environment that sits between development and staging. Add or remove rows to suit your project.

What to Capture for Each Environment

For every environment, document the following:

URL -- The base URL that developers and testers use to access the environment.
Credentials -- Do not store passwords or secrets in plain text in this file. Note where credentials are stored (for example, "in the team's shared password manager under the key staging-db") and how to request access.
Configuration differences -- Anything that differs from production: debug flags, third-party API keys pointing to sandbox accounts, feature flags, log verbosity, and so on.
Deployment method -- How code gets deployed to this environment (manual push, CI/CD pipeline, tagged release, and so on).
Owner / contact -- Who is responsible for keeping this environment healthy.

Template

Copy the sections below into your project documentation. Replace the placeholder text with real values.

Local

Item	Value
URL	`http://localhost:8000` (or as configured)
Database	SQLite file at `database/database.sqlite` (or as configured)
Setup	See `README.md` for initial setup instructions.
Notes	Each developer runs their own independent instance.

Development

Item	Value
URL	[Replace with dev environment URL]
Credentials	Stored in [replace with location, e.g. shared password manager].
Deployed via	[Replace: e.g. "GitHub Actions on push to `develop`"]
Config differences	[Replace: e.g. "Debug mode enabled. Stripe sandbox keys in use."]
Owner	[Replace with name or team]

Staging

Item	Value
URL	[Replace with staging URL]
Credentials	Stored in [replace with location].
Deployed via	[Replace: e.g. "GitHub Actions on push to `release/*` branches"]
Config differences	[Replace: e.g. "Production-like config. Uses sandbox payment gateway."]
Owner	[Replace with name or team]

Production

Item	Value
URL	[Replace with production URL]
Credentials	Stored in [replace with location].
Deployed via	[Replace: e.g. "GitHub Actions on tagged release"]
Config differences	None -- this is the reference environment.
Owner	[Replace with name or team]

Tips

Review this document every time you add or change an environment. Stale environment documentation causes as many problems as no documentation at all.
Never commit secrets. Use environment variables, a secrets manager, or a .env file that is listed in .gitignore.
Include a health-check URL for each shared environment so that monitoring can confirm it is up.