A year of history, one chart, and a read API with personal tokens
History: server load, memory and disks are also kept as hourly (four months) and daily (over two years) averages with lowest and highest; endpoint answers as hourly (four months) beside the daily figures. Charts ask for 24 hours to a year and are drawn from whichever is fine enough. A disk that two weeks call flat is looked at again over ninety days for the forecast. Built once from what is kept. One chart: TimeChart replaces the sparkline and the multi-line chart: hover and arrow-key readout, a lowest/highest band, gaps shown as gaps, the same ranges everywhere and the choice remembered. Used for server trends, comparing servers, a check's availability and answer times (Endpoints > History) and a server's availability. Read API: /api/v1 (servers, metrics, alerts, incidents, inventory, network, endpoints and their history, maintenance) with personal read-only tokens made under the user menu: shown once, hashed, 30/90/365 days or none, ten at most, removed with their owner. GET only. Documented in API.md. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
5e26e77340
commit
68b41b5586
47 files changed
+12360
-247
No files matched your search
@@ -3,6 +3,7 @@
|
||||
Ways for other systems to work with Homelab Manager:
|
||||
|
||||
- a read-only **`/metrics`** address for Prometheus, and **event webhooks** that are sent a signed message when something happens — both set up by an administrator under **Settings → API and webhooks** (the first two sections below);
|
||||
- a **read API** (`/api/v1`) with a personal, read-only token for each person, for scripts, Home Assistant and dashboards (the section after `/metrics`);
|
||||
- **heartbeats**: a cron job or script calls an address when it finishes, and the app speaks up when it doesn't (further down);
|
||||
- a **calendar feed** of what is coming up, for a phone's calendar to subscribe to (at the end).
|
||||
|
||||
@@ -85,6 +86,51 @@ All gauges. Labels are escaped as Prometheus requires.
|
||||
Some alerting ideas: `homelab_server_up == 0`, `homelab_server_disk_used_percent > 90`,
|
||||
`homelab_secret_expiry_days < 14`, `homelab_server_disk_days_to_full < 7`, `homelab_alerts{severity="critical"} > 0`, `time() - homelab_selfbackup_last_success_timestamp_seconds > 2 * 86400`.
|
||||
|
||||
## The read API — `/api/v1`
|
||||
|
||||
JSON about servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance — for a script, Home Assistant, a dashboard. It only reads.
|
||||
|
||||
```
|
||||
GET /api/v1/alerts
|
||||
Authorization: Bearer hlm_p_…
|
||||
```
|
||||
|
||||
- **A personal token**, made by whoever is going to use it under the user menu → **API tokens** (everyone signed in can, whatever their role). It is shown once, only its SHA-256 is kept, and it is that person's own: they see
|
||||
and remove theirs, nobody else's. It can last 30, 90 or 365 days or until removed, a person may have ten, and it stops working at once when removed — and when the person is.
|
||||
- The token goes in the `Authorization` header **only**. A token in the address is not accepted (addresses end up in logs). No token, a wrong one, an expired one and a removed one all get the same `401` with a JSON body.
|
||||
- **Only `GET`** (and `HEAD`). Any other verb is `405`, with a token or without: there is nothing here that changes anything.
|
||||
- A token sees what its owner sees on the pages — no secrets, no settings, no passwords, no tokens of servers. Requests are limited to 300 a minute from one address. Answers are `Cache-Control: no-store`.
|
||||
- Dates are ISO 8601 in UTC, sizes are bytes, percentages are 0–100. An address inside the app (`url`) is a full address, built from `APP_BASE_URL`.
|
||||
|
||||
| Address | What it answers |
|
||||
|---|---|
|
||||
| `GET /api/v1` | The list of these addresses. |
|
||||
| `GET /api/v1/me` | Whose token this is: the person's name and role, and the token's name and end. |
|
||||
| `GET /api/v1/servers` | Every server: `status` (`online`, `offline`, `unknown`), `lastSeenAt`, `tags`, `ipAddresses`, `cpu`, `memory`, `disks` (with `usedPercent`), `updates`, `hardware`, `url`. Filter with `?tag=` and `?status=`. |
|
||||
| `GET /api/v1/servers/:id` | One server, the same shape. |
|
||||
| `GET /api/v1/servers/:id/metrics?days=` | Its load, memory and disks as lines of points, 1 to 365 days (7 by default). Points over more than 35 days are hours' or days' averages, with `lo` and `hi`. Disks also carry a `trend` and, when rising steadily, `daysToFull`. |
|
||||
| `GET /api/v1/alerts` | What is wrong now: `needingAttention` (critical, warning, acknowledged), `counts`, `couldntCheck`, and `alerts` with `severity`, `category`, `message`, `silenced`, `flapping`, `target`, `causedBy`, `acknowledgement` (who, when, note, until) and `url`. Filter with `?severity=`, `?category=`, `?acknowledged=true|false`, `?silenced=true|false`. |
|
||||
| `GET /api/v1/incidents?status=&limit=` | The record of alerts that began and ended: `open` or `resolved`, newest first, up to 500 (100 by default). |
|
||||
| `GET /api/v1/incidents/:id` | One incident with its timeline. |
|
||||
| `GET /api/v1/inventory` | The hardware: maker, model, serial, where, bought, warranty, end of support, power. |
|
||||
| `GET /api/v1/network` | Switches, access points and gateways read from UniFi (state, address, uptime, firmware, uplink), the networks and Wi-Fi names, and which server is plugged into which device. |
|
||||
| `GET /api/v1/endpoints` | The checks: `status` (`up`, `down`, `unknown`, `paused`), last answer, certificate end, 24-hour and 7-day uptime. |
|
||||
| `GET /api/v1/endpoints/:id/history?days=` | A check's availability and answer times over 1 to 365 days, as points, from each answer (up to 2 days), the hourly figures (up to 120) or the daily ones. |
|
||||
| `GET /api/v1/maintenance` | What is under maintenance now (`active`) and what is coming (`upcoming`). |
|
||||
|
||||
```json
|
||||
{ "generatedAt": "2026-10-20T09:14:02.511Z",
|
||||
"needingAttention": { "critical": 1, "warning": 0, "acknowledged": 1 },
|
||||
"alerts": [
|
||||
{ "id": "offline:offline:server:3", "severity": "critical", "category": "offline", "source": "Server",
|
||||
"message": "anna hasn't reported for 9 h", "silenced": false, "flapping": false,
|
||||
"target": { "type": "server", "id": 3, "name": "anna" }, "causedBy": null, "affects": [],
|
||||
"acknowledgement": { "by": "Ada", "at": "2026-10-20T08:01:00.000Z", "note": "On it", "until": "2026-10-20T12:01:00.000Z", "assignee": "Ada" },
|
||||
"url": "https://hm.example.lan/servers/3" } ] }
|
||||
```
|
||||
|
||||
Errors are JSON too: `{ "error": "unauthorized" | "read_only" | "not_found" | "invalid_id", "message": … }`. In Home Assistant, a `rest` sensor with the token in `headers:` and `value_template: "{{ value_json.needingAttention.critical }}"` is enough for a count of what needs attention.
|
||||
|
||||
## A Grafana dashboard
|
||||
|
||||
Settings → API and webhooks → **Download the dashboard** (administrators) gives `homelab-manager-dashboard.json`; the same file is at
|
||||
|
||||
Reference in new issue
Block a user