# Environment Requirements

## Environment Loading

- Environment values are loaded from process environment.
- `.env` is supported through `python-dotenv` at app startup.
- Configuration is cached in memory after first load.

Source implementation: `app/config.py`

## Variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `APP_USERNAME` | `admin` | Login username accepted by the dashboard. |
| `APP_PASSWORD` | `changeme` | Plaintext password used when hash is not provided. |
| `APP_PASSWORD_HASH` | unset | Bcrypt hash used instead of plaintext password when present. |
| `SESSION_SECRET` | `change-this-secret` | Session signing secret for cookie middleware. |
| `SESSION_COOKIE_SECURE` | `false` | When true, session cookie is sent only over HTTPS. |
| `RPC_TIMEOUT_SECONDS` | `15` | Timeout for Bitcoin RPC HTTP requests. |
| `METRICS_SAMPLER_INTERVAL_SECONDS` | `60` | Background metrics sampling interval in seconds. |
| `DATA_DIR` | `./data` | Data directory root. Created if missing. |
| `DB_PATH` | `./data/dashboard.db` | SQLite file path. Overrides default path under `DATA_DIR`. |

## Validation and Normalization Rules

- `METRICS_SAMPLER_INTERVAL_SECONDS` minimum is clamped to `15`.
- `SESSION_COOKIE_SECURE` accepts truthy values:
  - `1`
  - `true`
  - `yes`
  - `on`
- `DB_PATH` parent directory is created automatically when needed.

## Security Guidance

Production baseline:

1. Do not use default `APP_USERNAME`.
2. Use `APP_PASSWORD_HASH` instead of plaintext password where possible.
3. Use a long random `SESSION_SECRET`.
4. Set `SESSION_COOKIE_SECURE=true` when served over HTTPS.
5. Scope dashboard network access to trusted hosts only.

## Example `.env`

Reference example is provided in `.env.example`.

See `doc/build-and-deploy.md` for environment injection in Docker Compose.