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
@@ -254,7 +254,7 @@ audit log (as `session` / `login_failed`, with the address and a short reason),
|
||||
Every response carries `frame-ancestors 'none'`, `X-Frame-Options`, `nosniff` and a no-referrer-to-other-sites policy. In production the app
|
||||
refuses to start without a `SESSION_SECRET`, and warns if it is still the placeholder from `.env.example`.
|
||||
Things to know: the first account to sign in becomes admin, so sign in yourself first on a new install. A session lasts up to 7 days after last use,
|
||||
and disabling someone in Authentik does not end it — delete them on the Users page (or end the session under Users → *Signed in now*) and it ends at once.
|
||||
and disabling someone in Authentik does not end it — end the session under Users → *Signed in now* and it ends at once (accounts themselves are not deleted in the app).
|
||||
If Authentik uses a certificate from an internal CA, point Node at the CA with `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` rather than turning verification
|
||||
off with `NODE_TLS_REJECT_UNAUTHORIZED=0`.
|
||||
|
||||
@@ -597,7 +597,7 @@ wrong — is a *critical* alert at once, with what it said. `/start` before the
|
||||
(`--data-raw "3.2 GB copied"`, or `?msg=`) is kept as a note, up to 200 characters. A heartbeat can be linked to the server the job runs on, so maintenance there silences
|
||||
it and the server's tags route it. Everyone can look; only administrators see the addresses, make, change and remove heartbeats, or give one a **new address** if it got out.
|
||||
The address needs no sign-in (it is a token, like an agent's), and all it can do is say "I'm alive": it can't read anything. Calls are limited per address, and an
|
||||
unknown token and a wrong path are answered alike. They also appear on the dashboard and in `/metrics`; the last two weeks of calls are kept. The format is in [API.md](API.md).
|
||||
unknown token and a wrong path are answered alike. They also appear on the dashboard and in `/metrics`; the last two weeks of calls are kept. The format is in [docs/HEARTBEATS-AND-CALENDAR.md](docs/HEARTBEATS-AND-CALENDAR.md).
|
||||
|
||||
**Coming up** (Operations → Coming up, and a card on the dashboard). Everything with a date ahead in one list, nearest first: secrets, domains and certificates that
|
||||
expire (including the ones endpoint checks see), Tailscale keys that are expiring, hardware warranties and end of support, planned and **recurring** maintenance, restore
|
||||
@@ -684,7 +684,7 @@ expire — to a request with a metrics token (a bearer token made on that page,
|
||||
once, only its hash kept). Event webhooks send a signed JSON message to a URL when an
|
||||
alert begins or ends or maintenance starts or finishes, for Home Assistant, n8n or a
|
||||
status board. Both are described, with the exact series and message formats, in
|
||||
[API.md](API.md).
|
||||
[docs/PROMETHEUS-GRAFANA.md](docs/PROMETHEUS-GRAFANA.md) and [docs/WEBHOOKS.md](docs/WEBHOOKS.md).
|
||||
|
||||
**Monthly report** (Operations → Monthly report; and, if switched on, a message on a day of the month). How a calendar month went, on one page that can be read, printed and copied as text:
|
||||
**availability** (servers, from when each stopped reporting and reported again; endpoints, from every check's answers, kept day by day for years; integrations), **incidents** (how many began and
|
||||
@@ -751,7 +751,7 @@ asked. It has rows for what needs attention, servers (with a server picker), dis
|
||||
filling up, SMART health, SSD wear, temperature, ZFS pools), backups (guests by state, age
|
||||
of each newest backup, the app's own backup) and secrets, power and the app itself. It is
|
||||
built from the same code as `/metrics`, and a test checks that it only asks for series that
|
||||
are really served. See [API.md](API.md).
|
||||
are really served. See [docs/PROMETHEUS-GRAFANA.md](docs/PROMETHEUS-GRAFANA.md).
|
||||
|
||||
**Since you last looked.** The dashboard opens with a card on what happened
|
||||
since you last pressed "Got it" (the first time, the last day; never more than
|
||||
@@ -812,7 +812,7 @@ months, days for over two years); a check's answers are kept as hours for four m
|
||||
stands for an hour or a day, a gap in the data is a gap in the line, and the range you pick is remembered for the next chart. **Endpoints → History…** opens a check's charts; a server's **History** section has its availability (30 days to a year) above its trends.
|
||||
|
||||
**API tokens.** The user menu → **API tokens** (for everyone signed in): make a read-only token for a script, Home Assistant or a dashboard — shown once, 30, 90 or 365 days or no end, ten at most, removed at once on request and with the person — and use it with `GET /api/v1/…` for
|
||||
servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance. The addresses, what each answers and an example are in [API.md](API.md).
|
||||
servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance. The addresses, what each answers and an example are in [docs/API.md](docs/API.md).
|
||||
|
||||
**UniFi network equipment.** Add a UniFi controller under Integrations (an API key, or a read-only local account; see INTEGRATIONS.md) and **Network → Network devices** lists its switches, access points and
|
||||
gateways: whether each is up (and since when it was not), IP and MAC address, uptime, firmware (with *update available*), the device it is connected through, how many things depend on it, and — on the *Networks & Wi-Fi* tab —
|
||||
@@ -929,7 +929,14 @@ needs the site to be served over HTTPS (browsers only offer install on secure
|
||||
origins; `localhost` also counts). The bundled service worker deliberately
|
||||
caches nothing, so an installed copy always shows the current build.
|
||||
|
||||
**More documentation**: [ROLES.md](ROLES.md) — who can see and do what;
|
||||
**More documentation** — the guides are in [docs/](docs/README.md):
|
||||
[docs/SSO.md](docs/SSO.md) — single sign-on with Authentik, what the setup needs, roles from groups, troubleshooting;
|
||||
[docs/API.md](docs/API.md) — the read API (`/api/v1`) and the other machine-facing addresses;
|
||||
[docs/PROMETHEUS-GRAFANA.md](docs/PROMETHEUS-GRAFANA.md) — `/metrics`, Prometheus, the Grafana dashboard and every series;
|
||||
[docs/WEBHOOKS.md](docs/WEBHOOKS.md) — event webhooks (signed JSON) and the notification webhook;
|
||||
[docs/HEARTBEATS-AND-CALENDAR.md](docs/HEARTBEATS-AND-CALENDAR.md) — cron-job heartbeats and the calendar feed;
|
||||
[docs/MONITORING.md](docs/MONITORING.md) — how monitoring works, from a reading to an alert.
|
||||
The references: [ROLES.md](ROLES.md) — who can see and do what;
|
||||
[NOTIFICATIONS.md](NOTIFICATIONS.md) — every notification the app sends and when;
|
||||
[INTEGRATIONS.md](INTEGRATIONS.md) — the credentials each integration needs;
|
||||
[DATABASE.md](DATABASE.md) — the database tables, columns and relationships;
|
||||
|
||||
Reference in new issue
Block a user