Configuration and environment
Use this skill when
- The server will not start because of missing or invalid configuration.
- Bootstrapping a new deployment environment and wiring real env vars or secrets.
- Behaviour differs between environments and the question is whether env loading is the cause.
- The main problem is repo-owned runtime config drift, such as a missing Cloudflare Worker binding in
wrangler.toml, wrangler.json, or wrangler.jsonc, without schema or migration work.
Do not use this skill when
- The deeper concern is auth or sensitive-data exposure (use
security-basics).
- The blocker is standing up a multi-service stack rather than env loading itself (use
docker-compose-dev).
Inputs to gather
- The authoritative list of required and optional variables (usually
.env.example or README).
- The runtime platform (shell, CI, container) supplying env vars and whether
.env is used.
- Any repo-owned runtime config that supplies bindings or non-secret settings, such as
wrangler.toml, wrangler.json, or wrangler.jsonc.
- The health-check endpoint or equivalent runtime check used to confirm a good startup.
First move
- Compare real env vars and any
.env against .env.example or the repo's config loader, then inspect runtime config files like wrangler.* for missing bindings or drift before starting the service and hitting /health or the closest existing startup check.
Outputs
- A concrete config-drift diagnosis across real environment variables,
.env, .env.example, and runtime binding files such as wrangler.*.
- The required variable, binding, or loader changes needed for the service to start with the expected configuration contract.
- Startup or
/health verification showing the configuration was accepted, or an explicit blocker listing the missing required config.
Catalog position
Keep this easy to reach for startup failures, env drift, and deployment/config debugging.
- Prefer
security-basics when the question is primarily about auth, sensitive exposure, or request-handling safety.
- Prefer
docker-compose-dev when the blocker is bringing up a multi-service stack rather than validating env loading itself.
- Prefer
database-migrations when the task changes D1 schema, migration files, or schema state rather than only fixing the Worker binding/config contract.
- Pair this with
rpi-workflow only when configuration work is part of a larger multi-phase change.
Loading priority (highest to lowest)
- Real environment variables (shell, CI secrets, runtime platform)
.env file (local developer override)
.env.example (documentation only — never loaded at runtime)
Setup
cp .env.example .env # start from the documented template
# edit .env with real values for your environment
Never commit .env. Add it to .gitignore.
Variable categories
Check .env.example or project README for authoritative var names. Common categories:
| Category |
Examples |
| Database |
DATABASE_URL — connection string |
| Auth |
Secret key / bearer token |
| Origins/CORS |
ALLOWED_ORIGINS — comma-separated list |
| TLS/Cookies |
SECURE_COOKIES, COOKIE_DOMAIN |
| Feature flags |
Enable/disable optional subsystems |
Required variables cause startup failure. Optional variables activate features.
Security constraints
- Production must use real env vars or a secrets manager — not
.env files.
- Never set
ALLOWED_ORIGINS=* when credentials or cookies are involved — use explicit origins.
- Enable secure cookies when behind HTTPS.
- Protect sensitive endpoints (metrics, admin) behind auth — do not leave them open by default.
- Never hardcode secrets in source code.
Verification commands
make build && ./bin/server # or equivalent start command
curl http://localhost:<PORT>/health
A healthy response confirms the configuration was accepted.
Anti-patterns
- Hardcoding secrets in source code or test fixtures
- Using
.env in production or CI
ALLOWED_ORIGINS=* with cookie/credential-based auth
- Silently ignoring missing required config — always fail fast at startup
Workflow
- Gather the startup failure or config symptom (missing env, bad binding, wrong environment).
- Compare live env /
.env against .env.example and the repo config loader.
- Inspect runtime config files (
wrangler.*, compose env, secrets mounts) for drift or missing bindings.
- Confirm required vs optional variables and fail-fast startup expectations.
- Apply the minimal config fix (example file, loader, binding, or secret wiring).
- Restart or re-run the service and hit
/health (or the closest startup probe).
- Document which variables are required in prod and that production must not rely on committed
.env files.
Guardrails
- Production must use real env vars or a secrets manager — never
.env files.
- Required variables must fail the server at startup, not silently at request time.
- Never commit
.env; only .env.example belongs in source.
- Never hardcode secrets in source code or test fixtures.
Validation
Run the verification commands above and confirm the service starts successfully, the health endpoint responds, and missing required variables still fail fast.
Reference files
- Read
references/examples.md when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.
- Read
references/edge-cases.md when the request is a near miss, partially matches this skill, or the first attempt fails.
scripts/check-config.sh — run with --help for a repeatable environment/configuration check.
1---2name: configuration-env3description: "Configure applications safely through environment variables, .env files, and repo-owned runtime config such as Wrangler bindings. Use for startup failures, environment drift, or deployment bootstrap."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/configuration-env7 version: 1.3.2 # x-release-please-version8 owner: mattriley9 category: ops10 audience: general-coding-agent11 maturity: stable12 kind: task13---1415# Configuration and environment1617## Use this skill when1819- The server will not start because of missing or invalid configuration.20- Bootstrapping a new deployment environment and wiring real env vars or secrets.21- Behaviour differs between environments and the question is whether env loading is the cause.22- The main problem is repo-owned runtime config drift, such as a missing Cloudflare Worker binding in `wrangler.toml`, `wrangler.json`, or `wrangler.jsonc`, without schema or migration work.2324## Do not use this skill when2526- The deeper concern is auth or sensitive-data exposure (use `security-basics`).27- The blocker is standing up a multi-service stack rather than env loading itself (use `docker-compose-dev`).2829## Inputs to gather3031- The authoritative list of required and optional variables (usually `.env.example` or README).32- The runtime platform (shell, CI, container) supplying env vars and whether `.env` is used.33- Any repo-owned runtime config that supplies bindings or non-secret settings, such as `wrangler.toml`, `wrangler.json`, or `wrangler.jsonc`.34- The health-check endpoint or equivalent runtime check used to confirm a good startup.3536## First move3738- Compare real env vars and any `.env` against `.env.example` or the repo's config loader, then inspect runtime config files like `wrangler.*` for missing bindings or drift before starting the service and hitting `/health` or the closest existing startup check.3940## Outputs4142- A concrete config-drift diagnosis across real environment variables, `.env`, `.env.example`, and runtime binding files such as `wrangler.*`.43- The required variable, binding, or loader changes needed for the service to start with the expected configuration contract.44- Startup or `/health` verification showing the configuration was accepted, or an explicit blocker listing the missing required config.4546## Catalog position4748Keep this easy to reach for startup failures, env drift, and deployment/config debugging.4950- Prefer `security-basics` when the question is primarily about auth, sensitive exposure, or request-handling safety.51- Prefer `docker-compose-dev` when the blocker is bringing up a multi-service stack rather than validating env loading itself.52- Prefer `database-migrations` when the task changes D1 schema, migration files, or schema state rather than only fixing the Worker binding/config contract.53- Pair this with `rpi-workflow` only when configuration work is part of a larger multi-phase change.5455## Loading priority (highest to lowest)56571. Real environment variables (shell, CI secrets, runtime platform)582. `.env` file (local developer override)593. `.env.example` (documentation only — never loaded at runtime)6061## Setup6263```bash64cp .env.example .env # start from the documented template65# edit .env with real values for your environment66```6768Never commit `.env`. Add it to `.gitignore`.6970## Variable categories7172Check `.env.example` or project README for authoritative var names. Common categories:7374| Category | Examples |75| ------------- | ---------------------------------------- |76| Database | `DATABASE_URL` — connection string |77| Auth | Secret key / bearer token |78| Origins/CORS | `ALLOWED_ORIGINS` — comma-separated list |79| TLS/Cookies | `SECURE_COOKIES`, `COOKIE_DOMAIN` |80| Feature flags | Enable/disable optional subsystems |8182Required variables cause startup failure. Optional variables activate features.8384## Security constraints8586- Production **must** use real env vars or a secrets manager — not `.env` files.87- Never set `ALLOWED_ORIGINS=*` when credentials or cookies are involved — use explicit origins.88- Enable secure cookies when behind HTTPS.89- Protect sensitive endpoints (metrics, admin) behind auth — do not leave them open by default.90- **Never hardcode secrets in source code.**9192## Verification commands9394```bash95make build && ./bin/server # or equivalent start command96curl http://localhost:<PORT>/health97```9899A healthy response confirms the configuration was accepted.100101## Anti-patterns102103- Hardcoding secrets in source code or test fixtures104- Using `.env` in production or CI105- `ALLOWED_ORIGINS=*` with cookie/credential-based auth106- Silently ignoring missing required config — always fail fast at startup107108## Workflow1091101. Gather the startup failure or config symptom (missing env, bad binding, wrong environment).1112. Compare live env / `.env` against `.env.example` and the repo config loader.1123. Inspect runtime config files (`wrangler.*`, compose env, secrets mounts) for drift or missing bindings.1134. Confirm required vs optional variables and fail-fast startup expectations.1145. Apply the minimal config fix (example file, loader, binding, or secret wiring).1156. Restart or re-run the service and hit `/health` (or the closest startup probe).1167. Document which variables are required in prod and that production must not rely on committed `.env` files.117118## Guardrails119120- Production must use real env vars or a secrets manager — never `.env` files.121- Required variables must fail the server at startup, not silently at request time.122- Never commit `.env`; only `.env.example` belongs in source.123- Never hardcode secrets in source code or test fixtures.124125## Validation126127Run the verification commands above and confirm the service starts successfully, the health endpoint responds, and missing required variables still fail fast.128129## Reference files130131- Read `references/examples.md` when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.132- Read `references/edge-cases.md` when the request is a near miss, partially matches this skill, or the first attempt fails.133- [`scripts/check-config.sh`](scripts/check-config.sh) — run with `--help` for a repeatable environment/configuration check.