For a one-person homelab, "on call" is when you can be reached. Settings -> Notifications -> When -> Away holds notifications while you are away (a banner on every page says so) and sends one digest when it ends, at its time or when you say you are back. Critical alerts can still come through. Quiet hours get the same "still send critical alerts" option. Escalation steps marked to send in quiet hours are sent while away too. What is held for one reason is not released while the other still holds it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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
- A new installation: README (install) → SSO.md (sign-in) → add servers and integrations in the app → MONITORING.md (what to expect) → BACKUP.md.
- Getting figures into Grafana: PROMETHEUS-GRAFANA.md.
- Getting alerts into something else: WEBHOOKS.md for pushes, API.md for asking.
- "Why did / didn't it alert?": MONITORING.md, then NOTIFICATIONS.md.
Conventions in these pages
- Examples use
https://hm.example.lanfor your own address (APP_BASE_URL), and tokens likehlm_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.