home-information/docs/dev/shared/environment-variables.md

Environment Variables

Adding (or removing, or renaming) an environment variable that the app reads touches four files. The cross-source drift check covers three of them automatically; the fourth — the app-side dataclass — relies on code review.

When to read this

Any time you add a new env-var dependency in app code: new integration credentials, a new feature flag, a new config knob. If the app reads it from os.environ (directly or via EnvironmentSettings), the ritual below applies.

Files to update

In recommended order:

1. src/hi/environment/server.py — EnvironmentSettings dataclass. Add a field with type and default. Use = None for required vars (absence raises ImproperlyConfigured); use an empty/zero/false default for optional.

   Field names are intentionally not required to match env-var names — EnvironmentSettings.SECRET_KEY reads DJANGO_SECRET_KEY, EnvironmentSettings.REDIS_HOST reads HI_REDIS_HOST, etc. The mapping (prefix-stripping and any explicit rename) is handled inside EnvironmentSettings. Pick a field name that reads naturally in app code; the env-var name follows the project's HI_ / DJANGO_ convention.

2. deploy/env-generate.py — two edits in the same file:

   • Add an entry to SETTING_SECTIONS under the appropriate section (or add a new section). Include a placeholder value and inline guidance on required vs. optional.
   • Assign a real value for the var, either in the __init__ overlay (self._settings_map.update(...)) for vars with a fixed default, or in generate_env_file() for vars filled in by interactive prompts.

   validate_settings() fails the run if a var is declared in SETTING_SECTIONS but never assigned (or vice versa), so this step is self-checking the moment you run make env-build.

3. install.sh — the heredoc between << INSTALL_ENV_FILE_EOF and INSTALL_ENV_FILE_EOF (the unique terminator lets install.sh --list-env-vars extract names unambiguously). Add a KEY=value line. Use a literal default for fixed-value vars or ${SHELL_VAR} interpolation for generated values (e.g. DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}).

4. local.env.example at the repo root — do not hand-edit. Regenerate from env-generate.py:

   python3 deploy/env-generate.py --example > local.env.example
   

Verification

After the four edits, run the drift check:

make env-drift-check

It compares the variable-name sets across install.sh, deploy/env-generate.py, and local.env.example and fails with a labeled diff on mismatch. Also wired into make check and the Check Env-Var Drift step in .github/workflows/django-tests.yml.

What drift-check does not cover

• EnvironmentSettings (server.py) — field names diverge from env-var names by design, so a structural cross-check would either be lossy or require a rename map per field. Verifying the dataclass change matches the env-var change is a code-review responsibility.
• Other code paths that read os.environ directly — app code should route env access through EnvironmentSettings, but nothing enforces it. If a contributor adds an os.environ.get('HI_SOMETHING_NEW') call elsewhere, only review catches it.

If a var reaches production without install.sh and the example file knowing about it, users won't have it set. The drift check is the first line; code review is the second.