Initial commit

doc/environment.md

@@ -0,0 +1,49 @@
+# 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.