# Environment Variables

The project's environment is owned by a single generator, not scattered across shell modules.
Every variable is documented INLINE next to its definition with a one-line `# ...` comment above the key.
This page is just a map of where to look.

## Where the defaults live

- [`default.env`](../../../default.env) holds the committed defaults for every static key (network defaults like DNS, subnet, gateway, domain included), each preceded by a one-line comment.
  Edit this file to change a default or to read the per-variable documentation.
- `.env` (gitignored) is generated by `make dotenv`, which delegates to `python -m cli.meta.env`.
  It combines `default.env` with runtime-resolved values (selected distro, GHA/Act flags, df/meminfo-derived cache sizes, sha256 secrets, repository owner, ...).
  Each line in `.env` is preceded by its own comment, so the file is self-describing.
  Open it after `make dotenv` to inspect the effective value-set together with its documentation.

## Regenerating

```bash
make dotenv
```

Override individual values by exporting them before `make dotenv`.
Already-set env vars take precedence over `default.env` defaults.

## Pipeline

- [`env/`](../../../utils/env/) (under `utils/`) holds the parser, runtime helpers, writer, and one handler module per dynamically-computed variable under [`handlers/`](../../../utils/env/handlers/).
- [`env/`](../../../cli/meta/env/) (under `cli/meta/`) provides the CLI entry point invoked as `python -m cli.meta.env`.
- [`load.sh`](../../../scripts/meta/env/load.sh) is the shell loader; it sources `.env` and auto-generates it on a cold clone.
  When the exported `INFINITO_DISTRO` differs from the one `.env` was generated for, it loads a set generated for that distro through `python -m cli.meta.env --output <file>` and leaves `.env` as it is.

## Variables NOT in `default.env`

A handful of variables are documented next to their consumer because they cannot have a static default:

- **Driver-injected** by `make compose-up` and the dev CLI (cache override paths like `INFINITO_CACHE_REGISTRY_PROXY_CONF`, the package-cache config paths, the frontend CA file).
  See [common.py](../../../cli/administration/deploy/development/common.py) and [compose.yml.md](../artefact/files/compose.yml.md).
- **Computed at container start** for `INFINITO_PATH`, set by [entry.sh](../../../scripts/docker/entry.sh).
- **Persisted on the deploy target** for `INFINITO_VERSION`, written by the [sys-version](../../../roles/sys-version/) role.
- **Compose literals** with no env-side knob, namely `GIT_SSL_NO_VERIFY` and `PYTHONHTTPSVERIFY`, documented in [compose.yml.md](../artefact/files/compose.yml.md).
- **Fork identity** for the operator's CI-redeploy shortcuts: `INFINITO_FORK_ACCOUNT` (defaults to the local OS username) and `INFINITO_FORK_REPOSITORY_URL` (composed as `https://github.com/$INFINITO_FORK_ACCOUNT/$INFINITO_FORK_REPOSITORY_NAME`), both set by handlers under [`utils/env/handlers/infinito/`](../../../utils/env/handlers/infinito/) (`fork_account.py`, `fork_repository_url.py`). The fork repository name itself lives in `default.env` as `INFINITO_FORK_REPOSITORY_NAME`.

## Role-scoped variables

App-specific container variables live next to the role that owns them, typically in `roles/<role>/templates/env.j2`, `roles/<role>/templates/bootstrap.env.j2`, or `roles/<role>/templates/playwright.env.j2`.
They are intentionally NOT centralised here so the app documentation and its generated env file stay in sync.