A failed service now raises an alert (and counts in /metrics and the public API) only when the server is told to watch it, by name or pattern, or * for all. Failed services that are not watched still show on the Host health card with a Watch button. Replaces the ignore list. 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.