bvandeusen
0596f1d9c1
Sweeps README, docs/, example configs, code docstrings, report and notification subject lines, plugin catalog URL default, and stray comments in Dockerfile/entrypoint.sh/.gitignore. Adds a legacy note to docs/core/configuration.md explaining the FABLEDSCRYER_* fallback. docker-compose DB credentials intentionally left as fabledscryer to preserve the existing pgdata volume.
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# Configuration
|
|
|
|
Roundtable 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` | `ROUNDTABLE_DATABASE_URL` | — | PostgreSQL async URL. **Required.** |
|
|
| `secret_key` | `ROUNDTABLE_SECRET_KEY` | auto-generated | Flask/Quart session signing key. Auto-generated and saved to `/data/secret.key` if not set. |
|
|
| `plugin_dir` | `ROUNDTABLE_PLUGIN_DIR` | `plugins` | Path to the plugins directory. |
|
|
|
|
**Resolution order for `database_url`:** env var `ROUNDTABLE_DATABASE_URL` → env var `ROUNDTABLE_DATABASE__URL` (legacy double-underscore) → `database.url` in `config.yaml`.
|
|
|
|
**Resolution order for `secret_key`:** env var `ROUNDTABLE_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/roundtable"
|
|
```
|
|
|
|
### Minimal env-only setup (Docker)
|
|
|
|
```bash
|
|
ROUNDTABLE_DATABASE_URL=postgresql+asyncpg://user:password@db/roundtable
|
|
```
|
|
|
|
A `.env` file is loaded automatically if present.
|
|
|
|
> **Legacy env vars:** `FABLEDSCRYER_*` env vars are still accepted as a fallback for existing deployments. They will be removed in a future release — migrate to `ROUNDTABLE_*` when convenient.
|
|
|
|
---
|
|
|
|
## 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 roundtable.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
|
|
|
|
`roundtable/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 |
|