bvandeusen
230b542015
- Rename package fablednetmon → fabledscryer throughout - Multi-dashboard: ownership, per-user defaults, HTMX edit (add/remove/reorder) - Read-only share tokens scoped to individual dashboards - Dashboard edit is HTMX-driven (no page reloads) - Plugin management system: remote catalog, download/install, hot-reload, in-app restart - plugin_index.py: fetch/cache remote index.yaml; default URL → bvandeusen/fabledscryer-plugins - plugin_manager.py: download_and_install_plugin, hot_reload_plugin, restart_app - ZIP extraction handles GitHub archive formats (name-v1.0.0/, name-main/) - Settings split into tabbed sections: General, Notifications, Ansible, Plugins - Plugins tab: catalog browser (HTMX), install/activate/update/restart actions - UI/branding: dark palette (#07071a), crystal ball SVG logo, animated star field, Libertinus Serif applied to headings, nav, labels, and section titles - Widget registry (core/widgets.py) for dashboard plugin integration - UPS widget.html (dashboard card) and settings/_tabs.html include - Migrations 0005–0008: dashboards, is_default, ownership, share tokens - docs/plugins/: writing-a-plugin.md updated with publishing guide, index.yaml.example template for fabledscryer-plugins repo Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# Fabled Scryer
|
|
|
|
A self-hosted network monitoring and infrastructure management hub for home servers. Fabled Scryer gives you a single pane of glass over your hosts, services, and automation — with live-updating dashboards, alerting, and Ansible integration.
|
|
|
|
---
|
|
|
|
## What It Does
|
|
|
|
- **Ping monitoring** — TCP/ICMP probes with live latency history and configurable thresholds
|
|
- **DNS monitoring** — resolution checks with optional expected-IP validation
|
|
- **Ansible** — browse playbooks, trigger runs, stream output live
|
|
- **Alerting** — threshold-based rules against any monitored metric, with email and webhook (Discord-compatible) notifications
|
|
- **Plugins** — extend with additional data sources; Traefik metrics included out of the box
|
|
- **Dashboard widgets** — all monitors and plugins contribute live-updating widgets
|
|
|
|
No JavaScript framework. No build step. No external workers or message brokers.
|
|
|
|
---
|
|
|
|
## Quick Start — Docker
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Set FABLEDSCRYER_DATABASE_URL in .env
|
|
|
|
docker compose up -d
|
|
```
|
|
|
|
Open `http://localhost:5000`. On first run you'll be prompted to create the admin account.
|
|
|
|
---
|
|
|
|
## Quick Start — Bare Metal
|
|
|
|
Requires Python 3.11+ and PostgreSQL.
|
|
|
|
```bash
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -e .
|
|
|
|
cp config.example.yaml config.yaml
|
|
# Edit config.yaml — set database.url at minimum
|
|
|
|
fabledscryer --host 0.0.0.0 --port 5000
|
|
```
|
|
|
|
ICMP ping requires `CAP_NET_RAW` or the `setuid` ping binary. TCP mode (the default) needs no elevated privileges.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Only two things must be set to run the app:
|
|
|
|
| What | How |
|
|
|---|---|
|
|
| Database URL | `FABLEDSCRYER_DATABASE_URL` env var or `database.url` in `config.yaml` |
|
|
| Secret key | Auto-generated on first run and saved to `/data/secret.key` |
|
|
|
|
Everything else — SMTP, webhooks, monitor intervals, Ansible sources, plugin settings — is configured through the web UI at `/settings/`.
|
|
|
|
---
|
|
|
|
## Plugins
|
|
|
|
Drop a directory into `plugins/` and enable it via the Settings UI. The Traefik plugin is included:
|
|
|
|
```
|
|
plugins/
|
|
└── traefik/ ← included; enable in Settings
|
|
```
|
|
|
|
See `docs/plugins/` for a full plugin development guide.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| `docs/architecture.md` | How the app works: startup sequence, routing, scheduler, DB pattern |
|
|
| `docs/core/configuration.md` | Bootstrap config, DB-backed settings, all setting keys and defaults |
|
|
| `docs/core/monitors.md` | Ping and DNS monitors: probe logic, metrics emitted, data models |
|
|
| `docs/core/alerting.md` | Alert rules, state machine, notification channels, template variables |
|
|
| `docs/core/ansible.md` | Playbook sources, run lifecycle, SSE streaming |
|
|
| `docs/plugins/overview.md` | Plugin system: how loading works, plugin.yaml schema, required exports |
|
|
| `docs/plugins/writing-a-plugin.md` | Step-by-step plugin development guide |
|
|
| `docs/plugins/traefik.md` | Traefik plugin: config, metrics, alert rule examples |
|
|
| `docs/reference/code-map.md` | Where every key function, model, and route lives in the codebase |
|