Documentation: guides in docs/, and the reference docs brought up to date
- New docs/ folder: SSO, API, Prometheus and Grafana, webhooks, heartbeats and calendar, how monitoring works, and an index; the old root API.md is split across them - Read API: alerts carry snoozedUntil - DATABASE.md: table and migration counts, indexes, relations, integration config, settings and internal flags, delete rules, retention - ROLES.md: the sidebar table rebuilt from the menu - NOTIFICATIONS.md, INTEGRATIONS.md, BACKUP.md, AGENT_UPDATE.md: what had drifted - README: links to the guides; accounts cannot be deleted in the app Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
24ae8db380
commit
c2e76262ca
17 files changed
+1773
-334
No files matched your search
@@ -0,0 +1,41 @@
|
||||
# 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](../README.md).
|
||||
|
||||
## Guides — this folder
|
||||
|
||||
| Guide | Read it when you want to … |
|
||||
|---|---|
|
||||
| **[SSO.md](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](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](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](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](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](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](../README.md) | What the app is, every feature, installation (Docker, arm64, development). |
|
||||
| [ROLES.md](../ROLES.md) | Viewer, operator, administrator: who sees which page and who can change what. |
|
||||
| [NOTIFICATIONS.md](../NOTIFICATIONS.md) | Every notification the app sends, what triggers it, what toggles it, routing, quiet hours, escalation. |
|
||||
| [INTEGRATIONS.md](../INTEGRATIONS.md) | What each integration and DNS provider needs (credentials, permissions) and what it does. |
|
||||
| [DATABASE.md](../DATABASE.md) | The database tables, columns and relationships. |
|
||||
| [BACKUP.md](../BACKUP.md) | What to back up, how (also while it runs), how to restore, and how to check a backup. |
|
||||
| [AGENT_UPDATE.md](../AGENT_UPDATE.md) | Keeping the agents on the servers up to date. |
|
||||
|
||||
## Where to start
|
||||
|
||||
- **A new installation:** [README](../README.md) (install) → [SSO.md](SSO.md) (sign-in) → add servers and integrations in the app → [MONITORING.md](MONITORING.md) (what to expect) → [BACKUP.md](../BACKUP.md).
|
||||
- **Getting figures into Grafana:** [PROMETHEUS-GRAFANA.md](PROMETHEUS-GRAFANA.md).
|
||||
- **Getting alerts into something else:** [WEBHOOKS.md](WEBHOOKS.md) for pushes, [API.md](API.md) for asking.
|
||||
- **"Why did / didn't it alert?":** [MONITORING.md](MONITORING.md), then [NOTIFICATIONS.md](../NOTIFICATIONS.md).
|
||||
|
||||
## 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](../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.
|
||||
Reference in new issue
Block a user