- Alerts can be acknowledged (note, assignee, duration); acknowledged alerts are left out of what needs attention (sidebar, dashboard strip, cards) but stay raised and counted by /metrics - Incidents: each time an alert is raised and goes away is recorded (alert_acks, alert_incidents, incident_notes, migration 0032), with a timeline of acks, maintenance, changes, update runs, related alerts and notes; Incidents page and a digest section - Backups of Homelab Manager's own database: daily checked VACUUM INTO copies, retention, download, check, upload, delete, and restore staged and applied at start-up before the database opens (pre-restore copy kept); alerts and /metrics for stale or failing backups - Docs: README, BACKUP, DATABASE, NOTIFICATIONS, ROLES, API; tests Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
793 lines
45 KiB
Markdown
793 lines
45 KiB
Markdown
# Database schema
|
||
|
||
Homelab Manager keeps its data in one SQLite file, accessed through
|
||
[drizzle-orm](https://orm.drizzle.team) and the libSQL client. The schema is
|
||
defined in one place — [`server/src/db/schema.ts`](server/src/db/schema.ts) —
|
||
and this document describes it. It was checked against a fresh database built
|
||
from the migrations, so the tables, columns, foreign keys and indexes below are
|
||
what the app actually creates.
|
||
|
||
- [The basics](#the-basics)
|
||
- [How the tables relate](#how-the-tables-relate)
|
||
- [Tables](#tables)
|
||
- [What's stored inside the JSON columns](#whats-stored-inside-the-json-columns)
|
||
- [Settings keys](#settings-keys)
|
||
- [What happens on delete](#what-happens-on-delete)
|
||
- [The Proxmox link's foreign key](#the-proxmox-links-foreign-key)
|
||
- [Retention and backups](#retention-and-backups)
|
||
- [Changing the schema](#changing-the-schema)
|
||
|
||
## The basics
|
||
|
||
| | |
|
||
|---|---|
|
||
| **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` … `0032`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
|
||
| **Tables** | 34 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`.
|
||
|
||
**Not in the database:**
|
||
|
||
- **Login sessions** are files in `SESSION_DIR` (default `../data/sessions`), not rows.
|
||
- **The encryption key** for integration credentials (`CREDENTIALS_ENCRYPTION_KEY`) and the session secret live in the environment, never in the file.
|
||
- **Agent tokens** are never stored: only a SHA-256 hash and a short prefix of each (`servers.api_token_hash`, `api_token_prefix`). The token itself is shown once, when the server is registered.
|
||
|
||
### Conventions
|
||
|
||
- **Primary keys** are `INTEGER PRIMARY KEY AUTOINCREMENT` named `id` — except `settings`, which uses its text `key`.
|
||
- **Booleans** are `INTEGER` 0/1 (shown as `bool` below).
|
||
- **Timestamps are text, in two formats**, so read them with care:
|
||
- Columns the database fills in itself (`created_at`, and most `updated_at`) use SQLite's `current_timestamp`: `2026-10-03 14:05:09`, **UTC, with no zone marker**. Treat it as UTC, not local time.
|
||
- Columns the app fills in (`last_seen_at`, `last_login_at`, `synced_at`, `last_checked_at`, …) use ISO 8601: `2026-10-03T14:05:09.123Z`.
|
||
- 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.
|
||
|
||
## How the tables relate
|
||
|
||
```mermaid
|
||
erDiagram
|
||
users ||--o{ audit_log : "actor (set null)"
|
||
integration_credentials ||--o{ integrations : "credential (set null)"
|
||
integration_credentials ||--o{ dns_providers : "credential (set null)"
|
||
dns_providers ||--o{ dns_zones_cache : "cascade"
|
||
dns_providers ||--o{ dns_records_cache : "cascade"
|
||
servers ||--o{ scheduled_tasks : "cascade"
|
||
servers ||--o{ server_links : "cascade"
|
||
servers ||--o{ server_metrics : "cascade"
|
||
servers ||--o{ server_ports : "cascade"
|
||
servers ||--o{ port_forwards : "optional (set null)"
|
||
integrations ||--o{ servers : "proxmox link (app clears it)"
|
||
integrations ||--o{ alert_tickets : "osTicket used (set null)"
|
||
```
|
||
|
||
Thirteen tables stand alone, with no foreign keys: `settings`, `secrets`,
|
||
`ipam_entries`, `domains`, `diag_log`, `notification_queue`,
|
||
`consistency_ignores`, `tag_definitions`, `share_links`, `maintenance_schedules`, `metrics_tokens`, `event_webhooks`, `alert_incidents`. `maintenance_windows` and `maintenance_aliases` also have no
|
||
foreign key — see [soft references](#soft-references-not-foreign-keys).
|
||
|
||
## Tables
|
||
|
||
Grouped by what they're for. "Null" in the notes means the column allows NULL;
|
||
everything not marked **NOT NULL** may be empty.
|
||
|
||
### People and activity
|
||
|
||
#### `users`
|
||
|
||
Everyone who has signed in through Authentik. The first one becomes admin.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `oidc_sub` | text NOT NULL, **unique** | The user's stable ID from Authentik (`sub` claim). This is what a session is matched against. |
|
||
| `email`, `name` | text | From the sign-in; may be empty. |
|
||
| `role` | text NOT NULL, default `viewer` | `admin` \| `operator` \| `viewer`. |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
| `last_login_at` | text | ISO. |
|
||
| `favorites` | text | JSON array of the page paths this person pinned to the top of their menu (`["/servers","/alerts"]`), up to 24. A path may carry a short query for a saved view of a page (`"/servers?status=offline"`). Follows them to any browser. |
|
||
| `dashboard_layout` | text | JSON object `{"hidden":["Gitea"],"order":{"Secrets":0,"DNS":1}}`: the dashboard cards this person hid and the order of the rest (lower first; a card with no entry goes last). Null = the default layout. Follows them to any browser. |
|
||
| `groups` | text | JSON array of the groups the identity provider reported at this person's last sign-in (null until they have signed in with groups available) — shown on the Users page, and what "roles from groups" works from. |
|
||
| `last_looked_at` | text | ISO time this person last pressed "Got it" on the dashboard's "Since you last looked" card; the next summary starts there (null = never: the last day is shown). |
|
||
|
||
#### `audit_log`
|
||
|
||
Who changed what. Written by the app on every change (see
|
||
[ROLES.md](ROLES.md) for who can read it).
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
|
||
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
|
||
| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`, `share_link` (a link made or removed — never the secret), `runbook`, `alert` (`ack`, `unack` — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. |
|
||
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
|
||
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
|
||
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
|
||
#### `diag_log`
|
||
|
||
One row per outbound call to an integration or DNS provider — the source of
|
||
the Diagnostic Log page and of the "integration down" alert.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `source` | text NOT NULL | The integration/provider type, e.g. `proxmox`, `cloudflare`. |
|
||
| `operation` | text NOT NULL | The adapter method, e.g. `listZones`. |
|
||
| `ok` | bool NOT NULL | |
|
||
| `latency_ms` | integer NOT NULL | |
|
||
| `error` | text | Message when `ok` is false. |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
|
||
#### `notification_queue`
|
||
|
||
Notifications held back during quiet hours, delivered as one digest and then
|
||
cleared.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `title`, `message` | text NOT NULL | |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
|
||
#### `maintenance_windows`
|
||
|
||
While a window is open, alerts about its target are silenced. An end time is
|
||
required, so a forgotten window can't silence real problems forever.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `target_type` | text NOT NULL | `server` \| `integration` \| `dns_provider`. |
|
||
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; a window whose target was deleted is simply ignored. |
|
||
| `reason` | text | |
|
||
| `started_at`, `ends_at` | text NOT NULL | ISO. |
|
||
| `created_by` | text | Name of the person who opened it. `Uptime Kuma sync` for mirrored ones. |
|
||
| `source` | text | `kuma:<integration id>:<maintenance id>` on windows mirrored from Uptime Kuma's schedule, so a later sync can find them again; `schedule:<schedule id>:<date>` on windows made from a recurring schedule (so one is made once, even if it was cancelled); NULL for ones started by hand. A window whose `started_at` is still in the future is *scheduled*: it silences nothing until it begins. A scheduled one that is cancelled has `ends_at` set equal to `started_at`. |
|
||
|
||
#### `maintenance_schedules`
|
||
|
||
A maintenance that repeats ("Sundays 02:00–04:00 on these servers"). It only says when:
|
||
the windows that silence alerts are ordinary `maintenance_windows` rows made a week
|
||
ahead and marked `schedule:<id>:<date>`.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL | e.g. "Patch night". |
|
||
| `reason` | text | |
|
||
| `targets` | text NOT NULL | JSON `[{"type":"server","id":3}, …]`. Polymorphic like `maintenance_windows`, so no foreign key; a deleted target is skipped. |
|
||
| `days` | text NOT NULL | JSON array of weekdays, 0 = Sunday … 6 = Saturday. |
|
||
| `start_time` | text NOT NULL | `HH:MM` on the clock of `timezone`. |
|
||
| `duration_minutes` | integer NOT NULL | |
|
||
| `timezone` | text NOT NULL | IANA name, so 02:00 stays 02:00 across summer and winter time. |
|
||
| `enabled` | bool NOT NULL, default 1 | Off makes no windows and takes back those that haven't begun. |
|
||
| `created_by` | text | |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `maintenance_aliases`
|
||
|
||
An address that Uptime Kuma's monitors use for something this app knows by another address, so the Uptime Kuma
|
||
maintenance sync can find it. Added on the Maintenance page.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `address` | text NOT NULL | A bare lowercase host: a name or an IP. |
|
||
| `target_type` | text NOT NULL | `server` | `integration` | `dns_provider`. |
|
||
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; an alias whose target was deleted is ignored. |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
Unique on (`address`, `target_type`, `target_id`).
|
||
|
||
### Servers
|
||
|
||
#### `servers`
|
||
|
||
A machine that reports in through the agent (or is registered by hand), plus
|
||
what it last reported.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL | Not unique. |
|
||
| `hostname` | text | |
|
||
| `os_type` | text NOT NULL, default `linux` | |
|
||
| `description` | text | |
|
||
| `api_token_hash` | text NOT NULL | SHA-256 of the agent's token. |
|
||
| `api_token_prefix` | text NOT NULL | First characters of the token, to tell tokens apart in the UI. |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
| `last_seen_at` | text | ISO; when the agent last reported. Drives "server offline". |
|
||
| `ip_addresses` | text | JSON `string[]`. Agent-reported. |
|
||
| `cpu_model` | text | Agent-reported. |
|
||
| `cpu_cores` | integer | |
|
||
| `cpu_load_percent` | real | Load average ÷ cores × 100 — an approximation, not instantaneous usage. |
|
||
| `mem_total_bytes`, `mem_used_bytes` | integer | |
|
||
| `disks` | text | JSON, see below. Agent-reported. |
|
||
| `listening_ports` | text | JSON, see below. What the agent sees bound on the host. |
|
||
| `last_port_scan` | text | JSON summary of the latest network scan *from this app*. |
|
||
| `tags` | text | JSON `string[]` of normalised tag names. |
|
||
| `proxmox_integration_id` | integer → `integrations.id` | The database has no `ON DELETE` rule here; the app clears the link itself — see [below](#the-proxmox-links-foreign-key). |
|
||
| `proxmox_node` | text | |
|
||
| `proxmox_guest_type` | text | `qemu` \| `lxc`. |
|
||
| `proxmox_vmid` | integer | The four `proxmox_*` columns are set together or cleared together (enforced by the API), by an admin — never by the agent. |
|
||
| `hide_proxmox_link` | bool NOT NULL, default 0 | Hides the "Proxmox link" card for servers that aren't Proxmox guests. Ignored while the server is actually linked. |
|
||
| `parent_server_id` | integer | The server this one runs on, set by an admin. **Not a foreign key** (a removed host's servers are cleared by the app). Null = work it out: a server linked to a Proxmox guest runs on the one server named after that guest's node. When the parent is down, this server's offline alert is folded under it. |
|
||
| `no_parent` | bool NOT NULL, default 0 | An admin said this server runs on nothing: no link, and no guess from its Proxmox node. Choosing a server by hand, or going back to automatic, clears it. |
|
||
| `pending_updates` | text | JSON `{"manager":"apt","count":5,"security":2,"rebootRequired":false,"reportedAt":"…"}` from the agent; null until it has said. `security` is null when the package manager can't tell. |
|
||
| `updates_pending_since` | text | ISO; when updates were first seen waiting (and none were before). Null when none are waiting. |
|
||
| `thresholds` | text | This server's own alert limits as JSON: `{"serverOfflineMinutes":…,"diskUsagePercent":…,"diskForecastDays":…,"backupStaleHours":…,"mounts":{"/data":{"percent":95,"ignore":true}}}`. Anything left out follows Settings; null when it follows Settings entirely. Ranges are checked on the way in (offline 15–10080 min, disk 50–99 %, forecast 0–90 days, backup 0–2160 h; 0 means off). |
|
||
| `host_health` | text | JSON `{"failedUnits":[{unit,description}],"smart":[{device,model,healthy,temperatureC,wearPercent}],"zfs":[{name,health,capacityPercent}],"reportedAt":"…"}`. Each part is present only if the agent reported it, and a report that leaves one out leaves it as it was. Null until an agent says anything. Judged by the health check and shown on the server's page. |
|
||
| `agent_version` | integer | Which version of the agent script runs on it, as the agent says in each report. Null until it says; an agent that predates the number counts as version 1. Compared with the scripts the app serves to say which agents are behind. |
|
||
|
||
#### `scheduled_tasks`
|
||
|
||
Cron jobs, systemd timers and Windows tasks the agent found on a server, plus
|
||
tasks added by hand.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||
| `schedule_type` | text NOT NULL | `cron` \| `systemd_timer` \| `windows_task` from agents; manual tasks may use others (`docker`, `backup`, `update`, `n8n_workflow`, `manual`). |
|
||
| `origin` | text NOT NULL, default `agent` | `agent` \| `manual`. Manual rows are never touched by agent sync. |
|
||
| `name` | text NOT NULL | |
|
||
| `command`, `schedule_expression`, `source` | text | |
|
||
| `enabled` | bool NOT NULL, default 1 | |
|
||
| `next_run_at` | text | |
|
||
| `raw_metadata` | text | JSON as the agent reported it. |
|
||
| `is_stale` | bool NOT NULL, default 0 | Set when the agent stops reporting the task. |
|
||
| `first_seen_at`, `last_seen_at` | text NOT NULL | SQLite UTC at first insert; later updates are written by the app. |
|
||
|
||
#### `server_links`
|
||
|
||
Admin-page bookmarks for a server (Dockge, Webmin, Cockpit, …). Shown on the
|
||
server's page and summarised under Operations → Admin Links.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||
| `label`, `url` | text NOT NULL | |
|
||
| `created_at` | text NOT NULL | SQLite UTC. |
|
||
|
||
#### `server_metrics`
|
||
|
||
A short history of each agent-reported server's load, memory and disk use, in
|
||
percent, for the Trends card on its page. At most one sample per server every
|
||
ten minutes however often its agent reports, kept for 35 days (older rows are
|
||
removed whenever a new sample is stored).
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||
| `metric` | text NOT NULL | `cpu`, `mem`, or `disk:<mount point>` (e.g. `disk:/data`). |
|
||
| `value` | real NOT NULL | Percent, 0–100, one decimal. |
|
||
| `recorded_at` | text NOT NULL | ISO. |
|
||
|
||
Index **`server_metrics_lookup_idx`** on (`server_id`, `metric`, `recorded_at`).
|
||
|
||
#### `server_ports`
|
||
|
||
A port on one server that's been seen open by a scan, or that someone wrote a
|
||
note about. Rows exist only while they carry information. What the *agent*
|
||
sees is stored on the server row instead (`servers.listening_ports`).
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
|
||
| `port` | integer NOT NULL | |
|
||
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
|
||
| `label`, `comment` | text | |
|
||
| `open` | bool NOT NULL, default 0 | True when the last scan connected to it. |
|
||
| `last_seen_open_at` | text | |
|
||
| `updated_at` | text NOT NULL | |
|
||
|
||
Unique index **`server_ports_unique`** on (`server_id`, `port`, `protocol`).
|
||
|
||
#### `port_forwards`
|
||
|
||
Manually recorded port openings on something this app doesn't monitor — a
|
||
router's port forward, an edge firewall rule, a cloud security group. It
|
||
records them; it can't check or change them.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `label` | text NOT NULL | |
|
||
| `external_port` | integer NOT NULL | |
|
||
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
|
||
| `server_id` | integer → `servers.id`, **set null** | Optional: the tracked server it points at. |
|
||
| `destination` | text | Anything else — a bare IP, an untracked device — or detail alongside `server_id`. |
|
||
| `internal_port` | integer | When NAT changes the port. |
|
||
| `source` | text | Free text: where the rule lives ("Home router", "OPNsense WAN rule"). |
|
||
| `comment` | text | |
|
||
| `created_at`, `updated_at` | text NOT NULL | |
|
||
|
||
### Integrations and credentials
|
||
|
||
#### `integrations`
|
||
|
||
A connected system: Proxmox, Synology, Semaphore, Tailscale, Gitea, Dockhand,
|
||
Uptime Kuma, phpIPAM, Proxmox Backup Server, osTicket.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `type` | text NOT NULL | `proxmox` \| `synology` \| `semaphore` \| `tailscale` \| `gitea` \| `dockhand` \| `uptimekuma` \| `phpipam` \| `pbs` \| `osticket`. |
|
||
| `name` | text NOT NULL | |
|
||
| `base_url` | text NOT NULL | For osTicket (a direct database connection) this holds the database host. |
|
||
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
|
||
| `config` | text | JSON of the *non-secret* settings, see below. |
|
||
| `enabled` | bool NOT NULL, default 1 | |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `integration_credentials`
|
||
|
||
The secret half of an integration or DNS provider, encrypted at rest.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL | `"<type>:<name>"`, for recognising a row when looking at the file. |
|
||
| `encrypted_secret` | text NOT NULL | `iv:authTag:ciphertext`, each in hex — AES-256-GCM with `CREDENTIALS_ENCRYPTION_KEY`. The plaintext is a JSON object of the secret fields (an API token, a password). Without the same key it can't be read. |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
The notification channels' credentials aren't in this table; they're encrypted in place in `settings` — see [Retention and backups](#retention-and-backups).
|
||
|
||
### DNS
|
||
|
||
#### `dns_providers`
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `provider_type` | text NOT NULL | `cloudflare` \| `loopia` \| `pihole` \| `azure` \| `cpanel` \| `technitium`. |
|
||
| `name` | text NOT NULL | |
|
||
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
|
||
| `config` | text | JSON, non-secret provider config (base URL, zone list, …). |
|
||
| `enabled` | bool NOT NULL, default 1 | |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `dns_zones_cache` and `dns_records_cache`
|
||
|
||
Local copies of what the providers returned at the last sync, so pages load
|
||
without calling every provider. The providers remain the source of truth.
|
||
|
||
`dns_zones_cache`
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
|
||
| `zone_id` | text NOT NULL | The provider's own identifier for the zone. |
|
||
| `zone_name` | text NOT NULL | |
|
||
| `synced_at` | text | ISO. |
|
||
|
||
Unique index **`dns_zones_cache_provider_zone_idx`** on (`provider_id`, `zone_id`).
|
||
|
||
`dns_records_cache`
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
|
||
| `zone_id` | text NOT NULL | The provider's zone identifier — matches `dns_zones_cache.zone_id` for the same provider, but is **not a foreign key**. |
|
||
| `record_id` | text NOT NULL | The provider's own record identifier. |
|
||
| `type` | text NOT NULL | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, … |
|
||
| `name`, `content` | text NOT NULL | |
|
||
| `ttl`, `priority` | integer | |
|
||
| `proxied` | bool | Cloudflare only. |
|
||
|
||
### Address and name tracking
|
||
|
||
#### `ipam_entries`
|
||
|
||
IP addresses with a label and notes, entered by hand or synced.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `ip_address` | text NOT NULL, **unique** | |
|
||
| `label`, `vendor`, `location`, `notes` | text | |
|
||
| `source` | text | Null = typed in by hand; otherwise the sync that created it: `tailscale`, `proxmox` or `phpipam`. A sync only updates rows it created itself and never overwrites a manual one. |
|
||
| `created_at`, `updated_at` | text NOT NULL | |
|
||
|
||
#### `domains`
|
||
|
||
Registered domains whose expiry is tracked.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL, **unique** | The registrable domain, lowercase ASCII. |
|
||
| `origin` | text NOT NULL, default `manual` | `manual` (typed in) or `zone` (created from a synced DNS zone, removed again when the zone goes away). |
|
||
| `expires_at` | text | `YYYY-MM-DD`, as the registry reports it. Null for registries that don't publish one. |
|
||
| `registrar` | text | |
|
||
| `lookup_source` | text | `rdap` \| `whois`. |
|
||
| `last_checked_at` | text | Last attempt. |
|
||
| `last_checked_ok_at` | text | Last *successful* attempt. |
|
||
| `last_check_error` | text | |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `secrets`
|
||
|
||
The expiry tracker for API tokens, certificates, passwords and the like. It
|
||
tracks *when* something expires; it does not store the secret itself.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL | |
|
||
| `type` | text NOT NULL, default `generic` | `api_token` \| `ssl_certificate` \| `password` \| `generic`. |
|
||
| `description`, `notes` | text | |
|
||
| `expiry_date` | text | `YYYY-MM-DD`. NULL = never expires (no status, no alert). For a certificate with a host to check, overwritten from the live certificate, and never NULL. |
|
||
| `warn_days` | integer NOT NULL, default 30 | How long before expiry to start reminding. |
|
||
| `check_host`, `check_port` | text / integer | Certificates only: read the expiry from the live certificate at this host:port. |
|
||
| `last_checked_at`, `last_check_error` | text | Result of the last live check. |
|
||
| `created_at`, `updated_at` | text NOT NULL | |
|
||
|
||
### Housekeeping
|
||
|
||
#### `settings`
|
||
|
||
Key/value store for app settings. One row per settings section (the value is
|
||
JSON) plus a few internal bookkeeping rows. Details under
|
||
[Settings keys](#settings-keys).
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `key` | text PK | |
|
||
| `value` | text NOT NULL | JSON (or a plain date/time for internal flags). |
|
||
| `updated_at` | text NOT NULL | |
|
||
|
||
#### `tag_definitions`
|
||
|
||
Tags themselves live on the servers that carry them (`servers.tags`). A row
|
||
here adds what a server can't: a tag that exists before anything uses it, and a
|
||
chosen colour. A tag with no row is simply one in use with an automatic colour.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL, **unique** | Normalised. |
|
||
| `color` | text | `#rrggbb`, or null for automatic. |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `consistency_ignores`
|
||
|
||
Consistency findings someone looked at and decided are fine.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `key` | text NOT NULL, **unique** | The finding's stable key, so it stays ignored across runs. |
|
||
| `title` | text NOT NULL | What the finding said when it was ignored, so the list still reads sensibly after it's gone. |
|
||
| `reason`, `created_by` | text | |
|
||
| `created_at` | text NOT NULL | |
|
||
|
||
#### `alert_tickets`
|
||
|
||
What the "open an osTicket ticket for an alert" feature remembers about each problem it has seen, so one problem opens one ticket however many
|
||
checks see it. A row is one *occurrence*: when an alert clears and later returns for good, that is a new row.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `alert_key` | text NOT NULL, indexed | The alert's id as the Alerts page shows it (e.g. `disk:server:3:/`). Not a foreign key — alerts aren't stored. |
|
||
| `status` | text NOT NULL | `pending` (seen, not yet in enough checks in a row), `open` (a ticket was opened), `baseline` (already there when the feature was switched on, left alone). |
|
||
| `seen_count` | integer NOT NULL, default 1 | Checks in a row it has been seen while pending. |
|
||
| `integration_id` | integer → `integrations.id`, **set null** | The osTicket integration the ticket went to. |
|
||
| `ticket_number` | text | osTicket's own number; null unless `open`. |
|
||
| `grouped` | bool NOT NULL, default 0 | Part of a summary ticket that covers several alerts (they share a number). |
|
||
| `severity`, `message` | text NOT NULL | What the alert said when it was recorded. |
|
||
| `first_seen_at`, `last_seen_at` | text NOT NULL | ISO. |
|
||
| `ticketed_at` | text | ISO; when the ticket was opened. |
|
||
| `cleared_at` | text | ISO; null while the alert is still active. Rows cleared more than 180 days ago are deleted. |
|
||
|
||
#### `alert_acks`
|
||
|
||
"I'm on it" for one alert. **One row per alert id.**
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `alert_key` | text NOT NULL, unique | The alert's stable id (e.g. `offline:offline:server:3`), the same key the Alerts page uses; **not a foreign key**. |
|
||
| `note` | text NOT NULL | Up to 500 characters; may be empty. |
|
||
| `assignee_user_id` | integer | → `users.id`, set to null if the user is removed. |
|
||
| `assignee_name` | text | The name as it was when handed over, so it still reads if the user is removed. |
|
||
| `acked_by` | text NOT NULL | |
|
||
| `acked_at` | text NOT NULL | ISO. |
|
||
| `until` | text | ISO; when it runs out. Null means until the alert is gone. |
|
||
| `last_seen_at` | text NOT NULL | ISO; the last time the alert was there. A row whose alert has been gone for 30 minutes is deleted. |
|
||
|
||
#### `alert_incidents`
|
||
|
||
One time an alert was raised and later went away. When the same alert comes back it is a new row. Information-only alerts are not recorded.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `alert_key` | text NOT NULL | The alert's id (indexed). Not a foreign key. |
|
||
| `severity`, `peak_severity` | text NOT NULL | As it is now (or was at the end), and the worst it got to. |
|
||
| `category`, `source`, `message`, `link` | text | As the Alerts page showed them; `message` is the latest wording. |
|
||
| `target_type`, `target_id`, `target_name` | text, integer, text | The server, integration or DNS provider it was about, when there is one (indexed). A plain reference, **not a foreign key**. |
|
||
| `caused_by` | text | The host whose outage this was folded under. |
|
||
| `opened_at` | text NOT NULL | ISO. |
|
||
| `resolved_at` | text | ISO; null while open. Set to when it first went missing, once it has been missing long enough. |
|
||
| `last_seen_at` | text NOT NULL | ISO. |
|
||
| `missing_since` | text | ISO; set while it has been missing from the last look(s), before it is called over. |
|
||
|
||
Resolved rows older than 400 days are deleted, with their notes.
|
||
|
||
#### `incident_notes`
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `incident_id` | integer NOT NULL | → `alert_incidents.id`, deleted with it. |
|
||
| `author` | text NOT NULL | The person's name at the time. |
|
||
| `body` | text NOT NULL | Up to 4000 characters. |
|
||
| `created_at` | text NOT NULL | ISO. |
|
||
|
||
#### `update_runs`
|
||
|
||
A playbook run in Semaphore for one server, wrapped in a maintenance window and followed until the server reports again.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `server_id` | integer NOT NULL | → `servers.id`, deleted with the server. |
|
||
| `integration_id`, `project_id`, `template_id` | integer NOT NULL | Which Semaphore, project and template. `integration_id` is a plain reference, **not a foreign key**, so history stays readable when an integration is removed. |
|
||
| `template_name`, `host_limit` | text NOT NULL | The template's name and ansible's `--limit` it was run with (never empty: an update run is for one server). |
|
||
| `task_id`, `task_status` | integer, text | Semaphore's run number and its own word for how it is going. |
|
||
| `window_id`, `window_created` | integer, bool | The maintenance window put round it, and whether this run made it (a window that was already there is extended and left to run out). |
|
||
| `status` | text NOT NULL | `running`, `waiting_for_host`, `done`, `failed` or `cancelled`. |
|
||
| `message` | text | What it says now, in words. |
|
||
| `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). |
|
||
|
||
#### `runbooks`
|
||
|
||
Notes about what to do when something is wrong, attached to a server, integration or DNS provider.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `target_type`, `target_id` | text, integer NOT NULL | `server` \| `integration` \| `dns_provider` and its ID. **Not a foreign key**; a note whose target was deleted is simply not shown. Indexed together. |
|
||
| `title`, `body` | text NOT NULL | The body is plain text (see README for the little formatting it understands); never rendered as HTML. |
|
||
| `category` | text | An alert category (`offline`, `disk`, …) the note is for; null = anything about the target. |
|
||
| `updated_by` | text | The person's name at the time. |
|
||
| `created_at`, `updated_at` | text NOT NULL | ISO. |
|
||
|
||
#### `assets`
|
||
|
||
The hardware inventory.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `name` | text NOT NULL | |
|
||
| `kind` | text NOT NULL, default `other` | `server`, `storage`, `network`, `power`, `client` or `other`. |
|
||
| `manufacturer`, `model`, `serial`, `location`, `rack_unit`, `notes` | text | |
|
||
| `purchase_date`, `warranty_until` | text | `YYYY-MM-DD`. |
|
||
| `purchase_price` | real | In the currency set under the `inventory` settings key. |
|
||
| `power_watts` | integer | Typical draw, for the running cost. |
|
||
| `server_id` | integer | The server this is, if it is one. A plain reference, **not a foreign key**: one whose server is gone shows as unlinked. |
|
||
| `created_at`, `updated_at` | text NOT NULL | ISO. |
|
||
|
||
#### `metrics_tokens`
|
||
|
||
Read-only access to `/metrics` for Prometheus. Only a hash of each secret is stored.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `label` | text NOT NULL | |
|
||
| `token_hash` | text NOT NULL, unique | SHA-256 of the secret, which is shown once and never stored. |
|
||
| `token_prefix` | text NOT NULL | The first characters, to tell tokens apart in the list. |
|
||
| `created_by` | text | |
|
||
| `created_at` | text NOT NULL | |
|
||
| `last_used_at` | text | ISO; updated at most once a minute. |
|
||
|
||
#### `event_webhooks`
|
||
|
||
URLs sent a signed JSON message when an alert begins or ends or maintenance starts or finishes.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `label` | text NOT NULL | |
|
||
| `url` | text NOT NULL | http or https, with no user name or password in it. |
|
||
| `secret` | text | Signs each message (HMAC-SHA256). Stored encrypted (`enc:v1:`) when an encryption key is set; never returned by the API. |
|
||
| `events` | text NOT NULL | JSON array of `alert.opened`, `alert.resolved`, `maintenance.started`, `maintenance.ended`. |
|
||
| `enabled` | bool NOT NULL, default 1 | |
|
||
| `created_by` | text | |
|
||
| `created_at` | text NOT NULL | |
|
||
| `last_attempt_at`, `last_result` | text | When it was last sent to and what came back (`200`, or what went wrong). |
|
||
|
||
#### `share_links`
|
||
|
||
Addresses that open a read-only wall display without signing in (Settings → Share
|
||
links). Only a hash of the secret is stored.
|
||
|
||
| Column | Type | Notes |
|
||
|---|---|---|
|
||
| `id` | integer PK | |
|
||
| `label` | text NOT NULL | What it is for, e.g. "Hall TV". |
|
||
| `token_hash` | text NOT NULL, unique | SHA-256 of the secret in the address; the secret itself is shown once and never stored. |
|
||
| `token_prefix` | text NOT NULL | The first characters of the secret, to tell links apart in the list. |
|
||
| `detail` | text NOT NULL, default `summary` | `summary` (numbers only) or `names` (also the names of what is wrong, in maintenance, and the integrations). |
|
||
| `created_by` | text | The administrator's name at the time. |
|
||
| `created_at` | text NOT NULL | |
|
||
| `expires_at` | text | ISO; null = until removed. |
|
||
| `last_used_at` | text | ISO; updated at most once a minute. |
|
||
|
||
## What's stored inside the JSON columns
|
||
|
||
| Column | Shape |
|
||
|---|---|
|
||
| `servers.ip_addresses` | `["10.0.0.5", "fd00::5"]` |
|
||
| `servers.disks` | `[{ "mount": "/", "sizeBytes": 32000000000, "usedBytes": 9000000000 }]` |
|
||
| `servers.listening_ports` | `[{ "protocol": "tcp", "port": 22, "address": "0.0.0.0", "process": "sshd" }]` |
|
||
| `servers.last_port_scan` | `{ "at": "<ISO>", "address": "10.0.0.5", "from": 1, "to": 1024, "open": 3, "refused": 1010, "filtered": 11, "responded": true }` |
|
||
| `servers.tags` | `["prod", "media"]` |
|
||
| `audit_log.detail` | Free-form per action — e.g. `{ "name": "pve1" }`, or for settings `{ "sections": [...], "changes": { "<section>": { "<field>": { "from": …, "to": … } } } }`. For the notification channels (Gotify, ntfy, SMTP, webhook) only the field *names* that changed are recorded, never values. |
|
||
| `integrations.config` | The non-secret fields for that integration type (table below). |
|
||
| `dns_providers.config` | Non-secret provider settings (base URL, zone list, …). |
|
||
|
||
**`integrations.config` by type** (the secret fields go to `integration_credentials` instead):
|
||
|
||
| Type | In `config` | Encrypted separately |
|
||
|---|---|---|
|
||
| `proxmox` | `url`, `tokenId`, `insecure` | `tokenSecret` |
|
||
| `pbs` | `url`, `tokenId`, `insecure` | `tokenSecret` |
|
||
| `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) |
|
||
| `phpipam` | `url`, `appId`, `insecure` | `token` |
|
||
| `osticket` | `host`, `port`, `database`, `username`, `tablePrefix` | `password` |
|
||
|
||
## Settings keys
|
||
|
||
Each section is one row in `settings`, with a JSON object as its value. Fields
|
||
that were never changed aren't stored; the app fills in defaults when reading.
|
||
|
||
| Key | Holds |
|
||
|---|---|
|
||
| `gotify`, `ntfy`, `smtp`, `webhook` | The four notification channels: enabled, address, and credentials (token / password / secret). The credential fields are stored encrypted (prefix `enc:v1:`) — see [Retention and backups](#retention-and-backups). |
|
||
| `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`). |
|
||
| `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. |
|
||
| `digest` | The weekly digest: `enabled` (false), `day` (0 = Sunday … 6; default 1, Monday) and `time` (`HH:MM`, default `08:00`), in the notification time zone. |
|
||
| `healthChecks` | `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30), `diskForecastDays` (14; 0 = off — how far ahead a filling disk is flagged on the Alerts page), `backupStaleHours` (48; 0 = off — how old a Proxmox guest's newest backup may be). A server can override each of these (see `servers.thresholds`). |
|
||
| `logRetention` | `enabled`, `retentionDays` (90), `intervalHours` (24). |
|
||
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
|
||
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
|
||
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
|
||
| `alertTickets` | Opening osTicket tickets for alerts: `enabled`, `integrationId`, `severities`, `categories`, `requesterName`/`requesterEmail`, `topicId`, `priorityId`, `notifyStaff`, `existingProblems`, `confirmChecks`, `summaryAbove`, `reopenAfterMinutes`. Edited under Settings → Alert tickets. The API address and key are on the osTicket integration, not here. |
|
||
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
|
||
|
||
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
|
||
settings, and aren't part of the app's settings object:
|
||
|
||
| Key | Value |
|
||
|---|---|
|
||
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
|
||
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
|
||
| `_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:healthActiveConditions`, `_internal:automationActiveConditions` | JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart. |
|
||
|
||
## 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 **DNS provider** | Its cached zones and records are deleted. |
|
||
| 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 **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)
|
||
|
||
These point at other rows by ID or name without the database enforcing it, so
|
||
a stale value is possible and the app treats it as "nothing there":
|
||
|
||
- `maintenance_windows.target_id` (→ a server, integration or DNS provider, by `target_type`)
|
||
- `maintenance_aliases.target_id` (the same, by `target_type`)
|
||
- `audit_log.target_id`
|
||
- `dns_records_cache.zone_id` (→ `dns_zones_cache.zone_id`, same provider)
|
||
- `servers.tags` (→ `tag_definitions.name`)
|
||
- `consistency_ignores.key`
|
||
|
||
## The Proxmox link's foreign key
|
||
|
||
`servers.proxmox_integration_id` is meant to clear itself when its integration
|
||
is deleted: `schema.ts` says `onDelete: "set null"`. The database doesn't do
|
||
that. Migration `0001` added the column as a plain
|
||
`REFERENCES integrations(id)`, and SQLite can't change a foreign key afterwards
|
||
without rebuilding the table, so the rule *in the database* is **no action**:
|
||
with foreign keys on, deleting an integration that a server points at is refused
|
||
with `FOREIGN KEY constraint failed`.
|
||
|
||
The app works around it rather than rebuilding the table. The delete route in
|
||
[`server/src/routes/integrations.ts`](server/src/routes/integrations.ts) first
|
||
clears the four `proxmox_*` columns on every server linked to that integration,
|
||
then deletes it, and the audit entry records how many servers were unlinked
|
||
(`unlinkedServers`). Deleting an integration therefore works whether or not
|
||
servers are linked to it. Anything that deletes integrations some other way —
|
||
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.
|
||
|
||
**Credentials at rest.** Integration and DNS provider credentials are
|
||
encrypted in `integration_credentials` (above). The notification channels'
|
||
credentials — the Gotify and ntfy tokens, the SMTP password and the webhook
|
||
secret — are in the `settings` rows, and are encrypted in place with the same key:
|
||
each is stored as `enc:v1:` followed by the same `iv:authTag:ciphertext` form, and the
|
||
rest of the row (URLs, topics, priorities) stays readable. The app decrypts them when
|
||
settings are read and encrypts them when they're written, so nothing else sees the
|
||
difference.
|
||
|
||
- A value saved by an older version (plain text) still works, and is encrypted the
|
||
next time the server starts.
|
||
- Without `CREDENTIALS_ENCRYPTION_KEY`, new notification credentials can only be
|
||
stored as plain text, and the server warns about it at startup. They are encrypted
|
||
at the next start once the key is set.
|
||
- If the key is changed or lost, the stored credentials can't be read: they show as
|
||
empty, and the server logs which ones. Enter them again under Settings →
|
||
Notifications. Editing a *different* field of the same channel meanwhile doesn't
|
||
overwrite the old ciphertext, so putting the right key back restores them.
|
||
|
||
Everything else in the file — IP addresses, hostnames, secret *names* and expiry
|
||
dates, the audit log — is readable by anyone who can read the file, so treat the
|
||
file and its backups as sensitive anyway.
|
||
|
||
**Backups.**
|
||
- **Settings → Backup** exports the settings, the integrations and the DNS
|
||
providers (with their credentials decrypted, then wrapped in a file encrypted
|
||
with a passphrase you choose). Importing merges the settings over the current ones, and adds
|
||
integrations and providers that don't exist yet (matched by type and name) — it never
|
||
overwrites an existing integration. It does **not** include servers, tasks,
|
||
secrets, IP addresses, domains, ports, tags, maintenance windows or logs.
|
||
- **A full backup** is a copy of the SQLite file, together with the value of
|
||
`CREDENTIALS_ENCRYPTION_KEY` — without that key the stored integration
|
||
credentials can't be decrypted. Copy the file while the app is stopped, or take a
|
||
snapshot while it runs, so you don't capture it mid-write. [BACKUP.md](BACKUP.md)
|
||
has the commands (the container has no `sqlite3` tool), a nightly script, and how to restore.
|
||
|
||
## Changing the schema
|
||
|
||
1. Edit [`server/src/db/schema.ts`](server/src/db/schema.ts).
|
||
2. From the repo root run `npm run db:generate`; it writes a new numbered SQL
|
||
file to `server/drizzle/` (and updates `server/drizzle/meta/`).
|
||
3. Read the generated SQL. SQLite can add a column but can't change or drop a
|
||
foreign key, so some changes become a table rebuild — which is also why the
|
||
[Proxmox link](#the-proxmox-links-foreign-key) described above is the way it is.
|
||
4. Start the server (or run `npm run db:migrate`); the migration is applied and
|
||
recorded in `__drizzle_migrations`.
|
||
5. Commit the schema, the SQL file and the `meta/` changes together, and update
|
||
this document.
|