Home Information - Your home, your data, organized.
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:
src/hi/environment/server.py—EnvironmentSettingsdataclass. Add a field with type and default. Use= Nonefor required vars (absence raisesImproperlyConfigured); use an empty/zero/false default for optional.Field names are intentionally not required to match env-var names —
EnvironmentSettings.SECRET_KEYreadsDJANGO_SECRET_KEY,EnvironmentSettings.REDIS_HOSTreadsHI_REDIS_HOST, etc. The mapping (prefix-stripping and any explicit rename) is handled insideEnvironmentSettings. Pick a field name that reads naturally in app code; the env-var name follows the project'sHI_/DJANGO_convention.deploy/env-generate.py— two edits in the same file:- Add an entry to
SETTING_SECTIONSunder 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 ingenerate_env_file()for vars filled in by interactive prompts.
validate_settings()fails the run if a var is declared inSETTING_SECTIONSbut never assigned (or vice versa), so this step is self-checking the moment you runmake env-build.- Add an entry to
install.sh— the heredoc between<< INSTALL_ENV_FILE_EOFandINSTALL_ENV_FILE_EOF(the unique terminator letsinstall.sh --list-env-varsextract names unambiguously). Add aKEY=valueline. Use a literal default for fixed-value vars or${SHELL_VAR}interpolation for generated values (e.g.DJANGO_SECRET_KEY=${DJANGO_SECRET_KEY}).local.env.exampleat the repo root — do not hand-edit. Regenerate fromenv-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.environdirectly — app code should route env access throughEnvironmentSettings, but nothing enforces it. If a contributor adds anos.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.