Files
Homelab-manager/docs
bobbanandClaude Sonnet 5.5 d78aba8bf9 Show cluster health in the Technitium DNS integration
Reads /api/admin/cluster/state (Technitium 14+): a Cluster table on the page,
alerts for a node unreachable for ten minutes (primary critical) and for a
secondary that has stopped taking the primary's configuration, and three
/metrics series. A server in no cluster shows nothing; a token that may not
view administration is told so and the rest of the read is unaffected.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-08 23:37:11 +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.