Files
Homelab-manager/docs
bobbanandClaude Sonnet 5.5 f86661f6c9 Speedtest Tracker, Costs, "Having trouble" on status pages, grouped Integrations and Dashboard
- Speedtest Tracker integration: charts, alerts for a slow line (median of the
  last three tests under a share of what is paid for) and for failing tests.
- Costs page (Records): things paid for by hand plus Hetzner's estimate, totals
  per currency, bills rolled forward into Coming up as Renewals.
- Status pages: a "Having trouble" state for things that answer but have an open
  alert; Speedtest reads as the internet.
- Integrations page and kind picker grouped like the sidebar (one shared types
  file); Notifications "What to send" shown one group at a time; Dashboard
  integration sections follow the menu groups, with tiles for integrations that
  have no widget.
- Docs, tests, and ROLES.md menu table brought up to date.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-26 23:23:46 +01:00
..

Documentation

Everything about running and integrating with Homelab Manager is in Markdown files in this repository. This folder holds the guides; the references (who can do what, every notification, every table, the credentials each integration needs) are next to the main README.

Guides — this folder

Guide Read it when you want to …
SSO.md Set up sign-in with Authentik: what is needed (HTTPS, reverse proxy, a signing key), the provider and .env settings, how roles can follow groups, and what to check when sign-in fails.
API.md Call Homelab Manager from a script, Home Assistant or another tool: personal tokens, every /api/v1 address with its answer, examples in curl, Python, Node and Home Assistant, and the other machine-facing addresses (agent reports, heartbeats, share links).
PROMETHEUS-GRAFANA.md Scrape /metrics with Prometheus, import the Grafana dashboard, copy a working Docker Compose and alerting rules, and look up every series.
WEBHOOKS.md Be told when something happens: signed event webhooks (alert opened/resolved, maintenance started/ended) with receivers in Node and Python, and the chat-style notification webhook.
HEARTBEATS-AND-CALENDAR.md Monitor a cron job (it calls an address when it finishes) or subscribe a calendar to what is coming up.
MONITORING.md Understand how monitoring works: what is watched and how often, how a reading becomes an alert, what acknowledge, snooze, maintenance and flapping each do, incidents, history, forecasts, and how to tune it.

References — next to the README

File What it is
README.md What the app is, every feature, installation (Docker, arm64, development).
ROLES.md Viewer, operator, administrator: who sees which page and who can change what.
NOTIFICATIONS.md Every notification the app sends, what triggers it, what toggles it, routing, quiet hours, escalation.
INTEGRATIONS.md What each integration and DNS provider needs (credentials, permissions) and what it does.
DATABASE.md The database tables, columns and relationships.
BACKUP.md What to back up, how (also while it runs), how to restore, and how to check a backup.
AGENT_UPDATE.md Keeping the agents on the servers up to date.

Where to start

Conventions in these pages

  • Examples use https://hm.example.lan for your own address (APP_BASE_URL), and tokens like hlm_p_xxxxxxxx… that you will replace.
  • A menu path such as Settings → API and webhooks is in the web interface; who may open it is in ROLES.md.
  • Sample answers have the shapes the app really sends (several were captured from a test installation and trimmed); the values are only illustrative.
  • Things that have not been checked against the real thing (a third-party system, a Grafana version, another identity provider) are said so where they come up.