3 min read
#project-docs#devops#deployments
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
.envfile that is listed in.gitignore. - Include a health-check URL for each shared environment so that monitoring can confirm it is up.