bvandeusen
88ab5b917e
Renames the Python package directory, CLI command, env var prefix, docker-compose service/container/image, Postgres role/db, and all visible branding. Marketing form is "Fabled Steward". Clean break from the previous rebrand: drops the fabledscryer→roundtable import shim in __init__.py and the FABLEDSCRYER_* env var fallback in config.py and migrations/env.py. Env vars are now STEWARD_* only. Heads-up for existing deployments: - Postgres user/db renamed fabledscryer → steward in docker-compose.yml. Existing volumes need the role/db renamed inside Postgres, or override POSTGRES_USER/POSTGRES_DB to keep the old names. - Host-agent systemd unit is now steward-agent.service. Existing agents keep running under the old name; reinstall to switch. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# Configuration
|
|
|
|
Steward uses a two-layer configuration system. Only the bare minimum needed to boot lives in files or environment variables. Everything else is stored in the database and managed through the Settings UI.
|
|
|
|
---
|
|
|
|
## Bootstrap Config (File / Env Vars)
|
|
|
|
These three values are read at startup from `config.yaml` and/or environment variables:
|
|
|
|
| Key | Env var | Default | Description |
|
|
|---|---|---|---|
|
|
| `database.url` | `STEWARD_DATABASE_URL` | — | PostgreSQL async URL. **Required.** |
|
|
| `secret_key` | `STEWARD_SECRET_KEY` | auto-generated | Flask/Quart session signing key. Auto-generated and saved to `/data/secret.key` if not set. |
|
|
| `plugin_dir` | `STEWARD_PLUGIN_DIR` | `plugins` | Path to the plugins directory. |
|
|
|
|
**Resolution order for `database_url`:** env var `STEWARD_DATABASE_URL` → env var `STEWARD_DATABASE__URL` (legacy double-underscore) → `database.url` in `config.yaml`.
|
|
|
|
**Resolution order for `secret_key`:** env var `STEWARD_SECRET_KEY` → `secret_key` in `config.yaml` → `/data/secret.key` file → auto-generate and write to `/data/secret.key`.
|
|
|
|
### Minimal config.yaml
|
|
|
|
```yaml
|
|
database:
|
|
url: "postgresql+asyncpg://user:password@localhost/steward"
|
|
```
|
|
|
|
### Minimal env-only setup (Docker)
|
|
|
|
```bash
|
|
STEWARD_DATABASE_URL=postgresql+asyncpg://user:password@db/steward
|
|
```
|
|
|
|
A `.env` file is loaded automatically if present.
|
|
|
|
---
|
|
|
|
## App Settings (Database-backed)
|
|
|
|
All runtime settings are stored in the `app_settings` table and editable through the web UI at `/settings/`. They are loaded into `app.config` at startup.
|
|
|
|
### All Settings and Defaults
|
|
|
|
| Key | Default | Description |
|
|
|---|---|---|
|
|
| `session.lifetime_hours` | `8` | How long a login session lasts |
|
|
| `data.retention_days` | `90` | How many days of ping/DNS/metric/ansible history to keep |
|
|
| `monitors.poll_interval_seconds` | `60` | How often ping and DNS checks run |
|
|
| `smtp.host` | `""` | SMTP server hostname |
|
|
| `smtp.port` | `587` | SMTP server port |
|
|
| `smtp.tls` | `true` | Use STARTTLS |
|
|
| `smtp.username` | `""` | SMTP login username |
|
|
| `smtp.password` | `""` | SMTP login password |
|
|
| `smtp.recipients` | `[]` | List of email addresses to notify |
|
|
| `webhook.url` | `""` | Webhook POST destination URL |
|
|
| `webhook.template` | see below | Jinja2 JSON template for webhook body |
|
|
| `ansible.sources` | `[]` | List of playbook source definitions |
|
|
| `ping.threshold.good_ms` | `50` | Latency below this is shown green in the ping UI |
|
|
| `ping.threshold.warn_ms` | `200` | Latency below this is shown yellow; above is orange |
|
|
|
|
Default webhook template:
|
|
```
|
|
{"content": "**{{ alert.state }}** — {{ alert.resource }} — {{ alert.rule_name }} ({{ alert.metric }} = {{ alert.value }})"}
|
|
```
|
|
|
|
### Reading and Writing Settings in Code
|
|
|
|
```python
|
|
from steward.core.settings import get_setting, set_setting
|
|
|
|
# Read
|
|
async with current_app.db_sessionmaker() as session:
|
|
host = await get_setting(session, "smtp.host")
|
|
|
|
# Write (must be inside a transaction)
|
|
async with current_app.db_sessionmaker() as session:
|
|
async with session.begin():
|
|
await set_setting(session, "smtp.host", "mail.example.com")
|
|
```
|
|
|
|
`get_setting()` returns the stored value or the default from `DEFAULTS` if the key has never been set.
|
|
|
|
### The DEFAULTS Dict
|
|
|
|
`steward/core/settings.py` contains the `DEFAULTS` dict — the canonical list of all recognised settings and their default values. Add new settings here to make them recognised by `get_all_settings()` and the settings UI.
|
|
|
|
---
|
|
|
|
## app.config Keys
|
|
|
|
After startup, `app.config` contains these additional keys (in addition to standard Quart keys):
|
|
|
|
| Key | Type | Source |
|
|
|---|---|---|
|
|
| `DATABASE_URL` | str | Bootstrap |
|
|
| `PLUGIN_DIR` | str | Bootstrap |
|
|
| `SESSION_LIFETIME_HOURS` | int | DB settings |
|
|
| `DATA_RETENTION_DAYS` | int | DB settings |
|
|
| `MONITORS_POLL_INTERVAL` | int | DB settings |
|
|
| `SMTP` | dict | DB settings, via `to_smtp_cfg()` |
|
|
| `WEBHOOK` | dict | DB settings, via `to_webhook_cfg()` |
|
|
| `ANSIBLE` | dict | DB settings, via `to_ansible_cfg()` |
|
|
| `PLUGINS` | dict | DB settings + plugin.yaml defaults, keyed by plugin name |
|