FabledSteward/README.md

Steward

A self-hosted network monitoring and infrastructure management hub for home servers. Steward 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

cp .env.example .env
# Set STEWARD_DATABASE_URL in .env

docker compose up -d

Open http://localhost:5000. On first run you'll be prompted to create the admin account.

This compose file builds the image locally and bind-mounts the source for live editing. To run a persistent instance off the published CI image instead, see Remote dev instance below.

---

Remote dev instance

For a long-lived instance on a remote server that tracks the dev CI line, use compose.deploy.yml. It pulls the published image (git.fabledsword.com/bvandeusen/steward:dev) rather than building, runs no source bind-mounts, and persists data in named volumes.

One-time prerequisite — registry push token (on the Git host). CI publishes the image, so the FabledSteward repo needs a push credential. The injected GITHUB_TOKEN lacks write:package, so create a Forgejo token scoped read:package + write:package and add it as the repo Actions secret REGISTRY_TOKEN. Until this exists, the publish CI job 401s and no :dev image is produced.

Standup (on the server):

# 1. Authenticate to the registry (read:package token is enough to pull)
docker login git.fabledsword.com -u <user>

# 2. Configure secrets
cp .env.example .env
# Set POSTGRES_PASSWORD. Leave STEWARD_SECRET_KEY unset to let the app
# generate + persist one on the /data volume.

# 3. Pull + boot
docker compose -f compose.deploy.yml up -d

Open http://<server>:5000 and create the admin account on first run. Devices send syslog to <server>:5514 (UDP or TCP); see docs/plugins/syslog.md.

Update to the latest dev build:

docker compose -f compose.deploy.yml pull
docker compose -f compose.deploy.yml up -d

Every push to dev that goes CI-green publishes a fresh :dev (and an immutable :<commit-sha> for rollback). To pin a specific commit, change the image: tag in compose.deploy.yml to :<sha>.

---

Quick Start — Bare Metal

Requires Python 3.11+ and PostgreSQL.

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

steward --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	STEWARD_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/core/backups.md	Steward's daily backup to an S3 bucket (Fabled Archives), what it holds, and steward restore
docs/core/timeline.md	The timeline: what it records from each source, areas and kinds, Settings → Timeline
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/plugins/prometheus.md	Prometheus plugin: scraping any /metrics endpoint, how series are stored, the Fabled Archives recipe
docs/plugins/syslog.md	Syslog plugin: sources, patterns and alerts, publishing port 5514 (ingress or host mode under Swarm)
docs/plugins/prometheus-widgets.md	Prometheus widget templates: writing, sharing and copying one in, every block, the format reference
docs/reference/code-map.md	Where every key function, model, and route lives in the codebase