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:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 00:09:43 +02:00
1 parent 24ae8db380
commit c2e76262ca
17 files changed
+1773 -334

No files matched your search

+51 -19
View File
@@ -23,8 +23,8 @@ what the app actually creates.
|---|---|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0033`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 35 application tables, plus drizzle's own `__drizzle_migrations`. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0051`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 61 application tables, plus drizzle's own `__drizzle_migrations`. |
**Not in the database, but beside it in the data folder:** the backups of the database itself (`backups/homelab-manager-….sqlite`, taken daily and on request; see [BACKUP.md](BACKUP.md)), and, only while a restore is waiting or has just happened, `restore-pending.sqlite` / `restore-pending.json` and `restore-result.json`.
@@ -44,7 +44,7 @@ what the app actually creates.
- Dates without a time (`secrets.expiry_date`, `domains.expires_at`) are `YYYY-MM-DD`.
- **JSON columns** are `TEXT` holding JSON; see [what's inside](#whats-stored-inside-the-json-columns).
- **Enumerations** (roles, types) are plain text — SQLite doesn't enforce the allowed values; the app does.
- **Indexes:** besides primary keys, the only indexes are the unique ones listed per table. There are no secondary indexes; the data sets here (hundreds to a few thousand rows) don't need them.
- **Indexes:** besides primary keys and the unique ones listed per table, a few plain indexes serve the tables that are read by range or by what they are about: `endpoint_results`, `heartbeat_pings`, `server_metrics`, `ha_readings` and `storage_samples` (by owner and time), `restore_tests`, `renewals`, `update_runs`, `patch_plan_runs`, `alert_incidents`, `incident_notes`, `alert_tickets`, `runbooks` and `status_items`. The other tables have a few thousand rows at most and need none.
## How the tables relate
@@ -78,12 +78,18 @@ erDiagram
servers ||--o{ port_forwards : "optional (set null)"
integrations ||--o{ servers : "proxmox link (app clears it)"
integrations ||--o{ alert_tickets : "osTicket used (set null)"
share_links ||--o{ status_items : "cascade"
users ||--o{ alert_acks : "assignee (set null)"
alert_incidents ||--o{ incident_notes : "cascade"
servers ||--o{ update_runs : "cascade"
patch_plans ||--o{ patch_plan_runs : "cascade"
endpoint_checks ||--o{ endpoint_daily : "cascade"
```
Twenty tables stand alone, with no foreign keys: `settings`, `notes`, `alert_rules`, `alert_snoozes`, `secrets`,
`ipam_entries`, `domains`, `diag_log`, `notification_queue`,
`consistency_ignores`, `tag_definitions`, `share_links`, `maintenance_schedules`, `metrics_tokens`, `event_webhooks`, `alert_incidents`, `dependencies`, `endpoint_checks`, `restore_tests`, `heartbeats`. `maintenance_windows` and `maintenance_aliases` also have no
foreign key — see [soft references](#soft-references-not-foreign-keys).
These 22 tables are without a foreign key to another table, and — but for `integration_credentials`, which `integrations` and `dns_providers` point at — with none from another table to them; where they refer to something else it is by id or name, see
[soft references](#soft-references-not-foreign-keys): `settings`, `secrets`, `ipam_entries`, `domains`, `diag_log`, `notification_queue`, `consistency_ignores`, `tag_definitions`,
`maintenance_windows`, `maintenance_aliases`, `maintenance_schedules`, `metrics_tokens`, `event_webhooks`, `restore_tests`, `dependencies`, `runbooks`, `renewals`, `assets`, `notes`,
`alert_rules`, `alert_snoozes` and `integration_credentials`.
## Tables
@@ -618,7 +624,7 @@ One row per endpoint check per UTC hour (`hour`, ISO): `total`, `ok`, `ms_sum`,
#### `api_tokens`
A person's personal read-only API tokens (see API.md): `user_id` (→ `users.id`, **cascade**: they go with the person), `label`, `token_hash` (SHA-256, unique — the secret itself is shown once and not kept), `token_prefix` (its first twelve characters, to tell tokens apart), `created_at`, `last_used_at` (written at most once a minute) and `expires_at` (null = until removed).
A person's personal read-only API tokens (see [docs/API.md](docs/API.md)): `user_id` (→ `users.id`, **cascade**: they go with the person), `label`, `token_hash` (SHA-256, unique — the secret itself is shown once and not kept), `token_prefix` (its first twelve characters, to tell tokens apart), `created_at`, `last_used_at` (written at most once a minute) and `expires_at` (null = until removed).
#### `renewals`
@@ -641,8 +647,8 @@ A playbook run in Semaphore for one server, wrapped in a maintenance window and
| `started_by` | text | |
| `started_at`, `task_ended_at`, `host_reported_at`, `finished_at` | text | ISO. |
| `updates_before`, `updates_after` | integer | The waiting count before, and from the report that came after. |
| `reboot_required` | bool | From that report. |
| `poll_errors` | integer | Consecutive times Semaphore didn't answer (ten ends the run). |
| `reboot_required` | bool NOT NULL, default 0 | From that report. |
| `poll_errors` | integer NOT NULL, default 0 | Consecutive times Semaphore didn't answer (ten ends the run). |
#### `runbooks`
@@ -1043,9 +1049,12 @@ What a status page shows, in order.
| `synology` | `url`, `username`, `insecure` | `password` |
| `semaphore`, `gitea`, `dockhand` | `url` | `token` |
| `tailscale` | `tailnet` | `apiKey` |
| `uptimekuma` | `url`, `username` | `password` (an API key, or the password on old installs) |
| `uptimekuma` | `url`, `username`, `loginUsername`, `syncMaintenance` | `password` (an API key, or the password on old installs), `loginPassword` |
| `phpipam` | `url`, `appId`, `insecure` | `token` |
| `osticket` | `host`, `port`, `database`, `username`, `tablePrefix` | `password` |
| `osticket` | `host`, `port`, `database`, `username`, `tablePrefix`, `apiUrl`, `apiInsecure` | `password`, `apiKey` |
| `unifi` | `url`, `username`, `site`, `selfHosted`, `insecure` | `apiKey` (or `password`, with `username`) |
| `npm` (Nginx Proxy Manager) | `url`, `email`, `insecure` | `password` |
| `homeassistant` | `url`, `insecure` | `token` |
## Settings keys
@@ -1061,6 +1070,7 @@ that were never changed aren't stored; the app fills in defaults when reading.
| `notifications` | Which events notify (`dnsAdd`, `healthAlerts`, …), the daily-reminder time (`secretCheckTime`, default `08:00`) and `timezone` (default `UTC`), and the integration-failure threshold (default 3). |
| `quietHours` | `enabled`, `start`, `end`. |
| `signIn` | Roles from groups: `roleFromGroups` (false), `groupsClaim` (`groups`), `adminGroups`, `operatorGroups`, `otherwise` (`viewer` or `keep`). |
| `profilePictures` | Where pictures of people come from: `identityProvider` (false) and `gravatar` (false). Either one means the server fetches pictures from an outside address; they are checked, kept for a day and served from this app. |
| `selfBackup` | The daily backup of this database: `enabled` (true), `time` (`HH:MM`, default `03:30`, in the notification time zone) and `keep` (14 — how many daily ones are kept). |
| `agents` | `autoUpdate` (false): whether agents that are behind replace themselves. |
| `inventory` | `currency` (a short name, may be blank) and `pricePerKwh` (null) — what the inventory's running cost is worked out with. |
@@ -1084,18 +1094,25 @@ settings, and aren't part of the app's settings object:
| `_internal:integration_history_since` | When the app first began writing integrations' failing / working-again moments; the uptime ribbons claim nothing earlier for integrations. |
| `_internal:alertTicketsBaselineDone`, `_internal:alertTicketsLastRun` | Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result. |
| `_internal:webPushVapid` | JSON `{publicKey, privateKey}`: the server's own key pair for web push, made the first time it is needed. The private half is encrypted like the other credentials. Replacing it (deleting the row) makes every browser subscribe again. |
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions`, `_internal:endpointActiveConditions` | JSON: the problems currently active (health checks; automation runs; endpoint checks and heartbeats), so each is announced once and again when it clears, and survives a restart. |
| `_internal:flapState` | JSON, by alert key: the recent raises of each alert and whether it is flapping (see NOTIFICATIONS.md), so a restart remembers what is being held. |
| `_internal:unifiSync`, `_internal:homeAssistantSync` | JSON, by integration id: how the last read of each controller or Home Assistant went (`at` is the last *successful* read; one older than twenty minutes is not judged). |
| `_internal:selfBackupLastAttempt` | JSON: how the last attempt to back this database up went (time, whether it worked, why not). |
| `_internal:endpointSuggestionsDismissed`, `_internal:dependencySuggestionsDismissed` | JSON arrays of the suggestion keys somebody said "not that" to. |
| `_internal:metricsRollupBackfilled`, `_internal:endpointHourlyBackfilled` | The time the hourly and daily summaries were first built from the samples already kept (once, after they were added). |
## What happens on delete
| Deleting… | Effect |
|---|---|
| a **server** | Its `scheduled_tasks`, `server_links` and `server_ports` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. |
| a **server** | Its `scheduled_tasks`, `server_links`, `server_ports`, `server_metrics`, `server_metrics_rollup`, `update_runs` and `network_server_links` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. Things that refer to it by id only (notes, to-do items, endpoint checks, heartbeats, alert rules, dependencies, runbooks, maintenance windows) stay, pointing at nothing — see below. |
| a **DNS provider** | Its cached zones and records are deleted. |
| an **integration** | What was read from it is deleted with it: UniFi devices, networks and server links, Home Assistant watched entities and readings, and the history of its storage pools (`storage_series`, `storage_samples`). |
| an **endpoint check**, a **heartbeat**, an **incident**, a **patch plan**, a **share link** | Their results and summaries (`endpoint_results`, `_hourly`, `_daily`), pings, notes, runs and status-page items. |
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
| an **integration** used for alert tickets | `alert_tickets.integration_id` is cleared; the history stays. |
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. |
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. Their personal API tokens and push subscriptions are deleted with them; to-do items and acknowledgements handed to them stay, with the assignee cleared and the name kept. (The app has no way to delete a user: the rules apply to a removal made in the database.) |
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
### Soft references (not foreign keys)
@@ -1111,6 +1128,10 @@ a stale value is possible and the app treats it as "nothing there":
- `dns_records_cache.zone_id` (→ `dns_zones_cache.zone_id`, same provider)
- `servers.tags` (→ `tag_definitions.name`)
- `consistency_ignores.key`
- `notes.target_id` and `todos.target_id` (→ a server or a network device, by `target_type`) and `runbooks.target_id`
- `alert_rules.server_id` (→ a server; a rule for a server that is gone judges nothing)
- `alert_acks.alert_key`, `alert_snoozes.alert_id`, `alert_tickets.alert_key` and `alert_incidents.alert_key` (→ an alert, by its id on the Alerts page: the same problem has the same id)
- `network_devices` ↔ `dependencies` and `maintenance_windows` with `device` as their type (→ `network_devices.id`)
## The Proxmox link's foreign key
@@ -1132,10 +1153,21 @@ a hand-written SQL statement, say — has to do the same first.
## Retention and backups
**Retention.** Only the two logs are trimmed: `audit_log` and `diag_log` entries
older than `logRetention.retentionDays` are deleted by the purge job (off by
default), and `notification_queue` is emptied each time the quiet-hours digest is
sent. Everything else stays until someone deletes it.
**Retention.** The two logs, `audit_log` and `diag_log`, are trimmed by the purge job once it is switched on (`logRetention`: off by default, then entries older than `retentionDays`
are deleted), and `notification_queue` is emptied each time the quiet-hours digest is sent. The history tables trim themselves:
| Table | Kept |
|---|---|
| `server_metrics` | 35 days of samples |
| `server_metrics_rollup` | hourly rows 120 days, daily rows about 800 days |
| `endpoint_results` | 14 days of every answer |
| `endpoint_hourly`, `endpoint_daily` | 120 days, and 800 days |
| `storage_samples` | 400 days (a pool not reported for 30 days is deleted with its readings) |
| `ha_readings` | 35 days |
| `heartbeat_pings` | 14 days |
| `alert_incidents`, `incident_notes` | 400 days after the incident resolved |
Everything else stays until someone deletes it.
**Credentials at rest.** Integration and DNS provider credentials are
encrypted in `integration_credentials` (above). The notification channels'