- 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>
71 lines
5.0 KiB
Markdown
71 lines
5.0 KiB
Markdown
# Heartbeats and the calendar feed
|
|
|
|
Two addresses that are not part of the [read API](API.md) and need no sign-in, because each carries its own token:
|
|
|
|
- **Heartbeats** — a cron job or script calls an address when it finishes, and Homelab Manager speaks up when it does not. This is how to monitor things the app cannot see by itself: a backup script,
|
|
a nightly sync, a certificate renewal.
|
|
- A **calendar feed** — what is coming up (expiries, warranties, maintenance), for a phone or desktop calendar to subscribe to.
|
|
|
|
How a missed heartbeat becomes an alert, a notification and an incident is in [MONITORING.md](MONITORING.md).
|
|
|
|
## Heartbeats — for cron jobs and scripts
|
|
|
|
### Setting one up
|
|
|
|
Administrators: **Monitoring → Heartbeats → Add a heartbeat**.
|
|
|
|
| Field | Notes |
|
|
|---|---|
|
|
| Name | what the job is, e.g. "Nightly backup" (up to 100 characters) |
|
|
| **Period** | how often the job should report, from 1 minute to 30 days |
|
|
| **Grace** | how much later than that is still fine, 0 minutes to a day (so a job that sometimes runs long is not a false alarm) |
|
|
| Server | optional: the server the job runs on. **Maintenance on that server silences the heartbeat's alerts**, and the alert links to it. |
|
|
| Notes | up to 500 characters |
|
|
|
|
Up to **100** heartbeats. Everyone signed in sees how each job is doing; only administrators see its **address** (with the token) — it is what lets anyone say "I'm alive" for the job. **New address** gives
|
|
a heartbeat a new token and the old address stops working at once.
|
|
|
|
### Calling it
|
|
|
|
The job calls its address when it finishes:
|
|
|
|
```
|
|
GET /api/heartbeat/<token> it worked
|
|
GET /api/heartbeat/<token>/start it began (optional: lets the next call say how long it took)
|
|
GET /api/heartbeat/<token>/fail it ran and went wrong: an alert at once
|
|
```
|
|
|
|
```sh
|
|
# in cron, after the job
|
|
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -o /dev/null https://hm.example.lan/api/heartbeat/hb_xxxxxxxxxxxxxxxxxxxxxxxx
|
|
|
|
# in a script, with a start, a failure and a note
|
|
curl -fsS -m 10 -o /dev/null https://hm.example.lan/api/heartbeat/hb_xxxx/start
|
|
./backup.sh && curl -fsS -m 10 -o /dev/null --data-raw "3.2 GB copied" https://hm.example.lan/api/heartbeat/hb_xxxx \
|
|
|| curl -fsS -m 10 -o /dev/null --data-raw "exit code $?" https://hm.example.lan/api/heartbeat/hb_xxxx/fail
|
|
```
|
|
|
|
- The token in the address is the whole of the access, and all it allows is to say "I'm alive": no session, no sign-in, and nothing can be read with it. GET, HEAD, POST and PUT all work.
|
|
Keep the address between the job and you; if it gets out, give the heartbeat a new address (the old one stops working at once).
|
|
- Anything sent with a call — the body of a POST, or `?msg=…` — is kept as a note, cut to one line of at most 200 characters.
|
|
- The answer is `200` and `OK`. A token that doesn't exist, a path other than the three, and a token of the wrong shape all get `404 Not found` in the same words. Calls are limited to 120 a minute from one address.
|
|
- A job is **late** when its period and the grace have passed since its last call (or since the heartbeat was made, if it has never called). That is a warning, announced once and again as cleared when the next call comes;
|
|
a call to `/fail` is critical and stays until a call that works. A heartbeat that is switched off still answers `200`.
|
|
- Both are alerts of the *Automation* category, so notification routing, tags, quiet hours and escalation apply, and maintenance on the server a heartbeat is linked to silences them.
|
|
|
|
## Calendar feed
|
|
|
|
An administrator makes a **calendar feed** under **Settings → Share links**: an address ending in `.ics` for a calendar app to subscribe to (Google Calendar, Apple Calendar, Outlook and Thunderbird all take "add a calendar from a URL").
|
|
|
|
```
|
|
GET /api/public/calendar/<token>.ics
|
|
```
|
|
|
|
- Like any share link, the token is the whole of the access; only its hash is kept, and the address is shown once, when the link is made. It can have an end date and can be removed at any time.
|
|
A link that doesn't work — never made, ended, removed, or one that opens a wall or a status page instead — gets `404` in the same words. Limited to 60 requests a minute from one address.
|
|
- It carries what **Coming up** lists, for the next year: all-day events for secrets, domains, certificates, Tailscale keys, warranties, end of support and restore tests, and events with a start and an end for planned and
|
|
recurring maintenance (every occurrence, which the page folds into one line). Updates that are waiting have no day and are not in it. Something that expired in the last week is kept; older is left out.
|
|
- With **kinds only**, an event says only what kind of thing it is ("A secret expires") and has no description, so it can go on a shared calendar. With **names** it carries the name and a link back to the app.
|
|
An event's `UID` is a hash of what it is and its date, the same on every fetch.
|
|
- The feed asks to be refreshed every six hours (`REFRESH-INTERVAL`); a calendar app decides for itself how often it does.
|