- Backups: a guest whose newest backup is older than its limit is an alert (backup kind), in the daily backup message, the digest and /metrics (homelab_backup_guests, ..._last_age_seconds) - Per-server thresholds (servers.thresholds, migration 0030): offline minutes, disk percent, forecast window, backup age, and per-disk limits or "leave alone"; applied everywhere the global ones were; saving clears the alerts cache - Update runs (update_runs, migration 0031): Update... on the Updates page puts the server under maintenance, runs a Semaphore playbook limited to it, waits for the host to report, and reports what is left and whether a restart is due; poller survives restarts - Notification toggle for update-run results; tests and docs Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
42 KiB
Database schema
Homelab Manager keeps its data in one SQLite file, accessed through
drizzle-orm and the libSQL client. The schema is
defined in one place — 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
- How the tables relate
- Tables
- What's stored inside the JSON columns
- Settings keys
- What happens on delete
- The Proxmox link's foreign key
- Retention and backups
- 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/ (0000 … 0031), applied automatically when the server starts. Which ones have run is recorded in the table __drizzle_migrations. |
| Tables | 31 application tables, plus drizzle's own __drizzle_migrations. |
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 AUTOINCREMENTnamedid— exceptsettings, which uses its textkey. - Booleans are
INTEGER0/1 (shown asboolbelow). - Timestamps are text, in two formats, so read them with care:
- Columns the database fills in itself (
created_at, and mostupdated_at) use SQLite'scurrent_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) areYYYY-MM-DD.
- Columns the database fills in itself (
- JSON columns are
TEXTholding JSON; see what's inside. - 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
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)"
Twelve 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. maintenance_windows and maintenance_aliases also have no
foreign key — see soft references.
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 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, 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 |
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. |
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.
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.
| 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. |
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. |
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). |
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, bytarget_type)maintenance_aliases.target_id(the same, bytarget_type)audit_log.target_iddns_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 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 has the commands (the container has nosqlite3tool), a nightly script, and how to restore.
Changing the schema
- Edit
server/src/db/schema.ts. - From the repo root run
npm run db:generate; it writes a new numbered SQL file toserver/drizzle/(and updatesserver/drizzle/meta/). - 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 described above is the way it is.
- Start the server (or run
npm run db:migrate); the migration is applied and recorded in__drizzle_migrations. - Commit the schema, the SQL file and the
meta/changes together, and update this document.