No description
  • Python 76.6%
  • Jinja 23%
  • Dockerfile 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
John Sturgeon 9bf6eee146
All checks were successful
Build and push image / build-and-push (push) Successful in 33s
Tests / pytest (push) Successful in 13s
Sort outages by last down, and acknowledge them all at once
The Alerts overview can now order outages by most recent down as well as by
count. Acknowledge all clears only the subjects the page listed, so one that
goes down after the page loads stays. Sort and filter bars across the app get
a smaller, quieter style.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 07:43:25 +01:00
.forgejo/workflows Add alert API with SQLite storage 2026-11-01 08:40:00 +01:00
app Sort outages by last down, and acknowledge them all at once 2026-11-14 07:43:25 +01:00
icon Add the dashboard's icon 2026-11-03 11:35:44 +01:00
n8n Show alerts no workflow handles yet as unrouted 2026-11-07 15:05:28 +01:00
tests Sort outages by last down, and acknowledge them all at once 2026-11-14 07:43:25 +01:00
.dockerignore Remove compose file now kept in homelab-stacks 2026-11-01 08:40:43 +01:00
.gitignore Add alert API with SQLite storage 2026-11-01 08:40:00 +01:00
Dockerfile Add app update checks through Grist and SSH 2026-11-01 19:01:55 +01:00
pyproject.toml Add alert hub pages and threshold notifications 2026-11-01 14:05:14 +01:00
README.md Show which host an app runs on, and keep one result per host 2026-11-03 11:32:12 +01:00
TODO.md Add a TODO item to upgrade Paperless 2026-11-05 20:55:34 +01:00
uv.lock Add alert hub pages and threshold notifications 2026-11-01 14:05:14 +01:00

Homelab Dashboard

One place for the homelab alerts that matter, and for the apps that need updating. The two are separate: alerts live in app/, updates in app/updates/, and neither feeds the other.

The alert hub is not a system status dashboard. It doesn't monitor anything, and it never claims a service is up. It only knows what alerts have told it, so quiet means nothing has been reported, not that everything is healthy. Checking services is the job of the monitors that send the alerts.

An alert flow is an alert's path from a source (Uptime Kuma, Pulse, ...) to n8n, to this app's database, and to you if necessary. n8n translates each source's JSON into the contract below, so adding a source doesn't change this app.

A lost alert can't be detected here: if a down never arrives, its subject stays quiet.

API

Every /api/* request needs Authorization: Bearer $ALERT_API_TOKEN.

curl -X POST http://localhost:8000/api/alerts \
  -H "Authorization: Bearer $ALERT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject": "minecraft", "state": "down", "occurred_at": "2026-11-01T15:04:05Z"}'
Field Meaning
subject The thing the alert is about: a stable lowercase name set by the alert flow, not the source's display name
state up or down
occurred_at When it happened according to the source, with a timezone offset. Stored as UTC
source Optional. Who reported it, such as Uptime Kuma. At most 50 characters
message Optional. Why, in the source's words, such as Keyword not found. Cut to 1,000 characters
payload Optional. The source's own webhook body, kept for inspecting on the subject page. Dropped, not rejected, over 64 KB

The optional fields only explain an alert to a person. Nothing the dashboard works out, such as outages or thresholds, uses them. A subject's page shows the source and message of the down that opened each outage, and every alert in it with its payload.

GET /api/alerts returns the newest alerts first. It accepts optional subject and limit (default 50, maximum 500) parameters. GET /ping is the unauthenticated healthcheck.

GET /api/summary returns the Overview's headline, for showing it elsewhere, such as a Glance custom-api widget:

{"state": "quiet", "headline": "All quiet", "detail": "4 subjects · 2 to review"}

state is down (past a threshold), waiting (down, within its threshold), quiet, or empty (no subjects).

GET /api/updates/summary returns the same shape for the Updates page, with a state of waiting (updates ready, apps that couldn't be checked, or out-of-date results), quiet, or empty (no apps).

GET /api/updates returns every app's latest update check. See Updates.

Pages

Page Shows
/ Home: a summary of alerts and of updates, anything down, outages past their threshold that resolved in the last 24 hours, and updates ready. Each summary links to the detail behind it
/alerts Only what needs attention: anything down, outages past their threshold that resolved in the last 24 hours, then any other outages in the last 30 days
/subjects Every subject, with its notification threshold and a delete action
/subjects/{subject} Outages per day for the last 30 days, and each outage
/updates Only apps that need attention: updates ready, then apps that couldn't be checked. Check now checks everything immediately
/apps Every app, with its installed version and latest check. ?status=update, unknown, pinned or current filters it

Each subject appears once on the Alerts overview, in its most urgent section. Acknowledging clears a subject from Home and the overview until its next outage; a subject that is still down can't be acknowledged. Unacknowledge on the Subjects page puts it back.

Alerts and updates only share Home, where they sit side by side. There is no combined status, so an available update never reads like an outage.

Each subject has one threshold: how long it can stay down before it should notify you. A subject's row is created by its first alert and stays until you delete it. Alerts are deleted after 30 days, unless one is the only record of an outage that is still open.

The pages have no login, so keep this app on the private network. Anyone who can reach it can acknowledge alerts and deploy any stack that has an update ready.

Notifications

Every minute, the app looks for open outages past their subject's threshold and POSTs them to NOTIFY_WEBHOOK_URL as a single event, so a storm of outages is one message rather than many. An n8n flow decides how and where that reaches you.

{
  "event": "threshold_passed",
  "subjects": [
    {
      "subject": "minecraft-s07",
      "started_at": "2026-11-01T08:41:59.063Z",
      "down_for": "10m",
      "url": "https://dashboard.example/subjects/minecraft-s07"
    }
  ],
  "dashboard_url": "https://dashboard.example/"
}

Each outage notifies once. A failed send retries on the next check, and is dropped if the outage resolves first. There are no recovery messages or reminders.

Setting Meaning
NOTIFY_WEBHOOK_URL Where to send events. Without it, nothing is sent
DASHBOARD_URL This app's base URL, used for the links in events

Updates

Every 2 minutes, the app reads Docker stacks from Komodo, so updating a stack clears it quickly. That only reads what Komodo already knows, and Komodo only looks for new images on stacks with Poll for Updates on, at its own interval, or when asked. Check now on /updates asks it for every stack, as its Check button does, then refreshes Docker and app results. It never deploys anything.

A Docker stack with an update ready has a Deploy button on / and /updates, which asks for confirmation and redeploys the whole stack through Komodo. The button reads Deploying… until Komodo finishes, then the app checks that stack again, so it leaves the list straight away. A failed deploy says so, with its log in Komodo. After 10 minutes the page stops waiting and the deploy carries on in Komodo. The app's own stack, named by KOMODO_STACK, is only started, because the app restarts with it. Apps checked over SSH have no button, because updating them is specific to each app. Every hour, it reads the list of other apps from Grist and runs app-version <name> over SSH on each app's host. Both also run at startup, and the results are saved. GET /api/updates reads those saved results, so showing them never contacts a host. This app knows nothing about any app: everything specific lives in the script on its host.

[
  {
    "source": "app",
    "name": "sonarr",
    "status": "update",
    "current_version": "4.0.14",
    "latest_version": "4.0.15",
    "detail": null,
    "error": null,
    "checked_at": "2026-11-01T08:41:59.063Z"
  }
]

source is app or docker. status is current, update, unknown or pinned. A failed check is unknown, with the reason in error, so a broken check never looks like an app that's up to date. If Grist can't be read, the last results stay and checked_at shows their age. Results older than 3 hours make /updates say they're out of date rather than "All up to date".

Docker results are one per stack, with images in detail and no version numbers. Komodo can only see a new image under the same tag. Tags like latest or postgres:16 get rebuilt, but an exact version like 1.2.3 or a digest never changes, so a stack with one of those is pinned, not current, unless Komodo reports an update. If Komodo can't be read, a single komodo result says why.

To add an app, add a row to the Grist table and make app-version on that host answer for it. To remove one, delete its row.

Grist column Type Meaning
name Text The name passed to app-version: letters, digits, ., _ and -, such as channels-dvr
host Reference to Hosts The host the app runs on
ip Formula $host.ip The address to connect to. This is the column the app reads
hostname Formula $host.hostname Optional. Shown beside the app's name. The same app can be listed once per host; without this column the address keeps them apart
update_notes Text Optional. How to update it, shown on its card while an update is ready. Web addresses become links and `code` shows as code; nothing else is formatted

Notes are read with every app check, so a change in Grist shows within the hour, or straight away with Check now.

app-version must print this and exit 0, or exit non-zero with the reason on stderr. A leading v on a version is ignored, and the two versions are only compared for difference:

{"installed": "4.0.14", "latest": "4.0.15"}

If the SSH key is locked with command=, the script gets no arguments, and the name arrives in $SSH_ORIGINAL_COMMAND as app-version <name> instead.

Setting Meaning
KOMODO_URL Komodo Core's base URL. Without all three Komodo settings, Docker isn't checked
KOMODO_API_KEY A Komodo API key with Execute on stacks, for Check now and Deploy. With read access only, those two fail and everything else works
KOMODO_API_SECRET That key's secret
KOMODO_STACK The Komodo stack this app runs in, which Deploy starts without waiting for. Default homelab-dashboard
GRIST_URL Grist's base URL. Without all three Grist settings, apps aren't checked
GRIST_DOC_ID The document holding the table
GRIST_API_KEY A key that can read that document
GRIST_HOST Optional Host header, for reaching Grist directly by IP
GRIST_TABLE The table's name. Default Apps
UPDATE_SSH_DIR Folder holding id_ed25519. Default /ssh
UPDATE_SSH_USER The user to connect as. Default app-version

A new host's SSH key is trusted on first connection and saved to known_hosts beside the database. If it later changes, that host's apps show as unknown. After a legitimate change, such as rebuilding a host, remove its line from that file.

SSH access is managed by the app_version deploy in homelab-pyinfra, for hosts tagged app-version in Grist. Never add the dashboard's key to Key_grants: that gives it the host user's full access.

Development

uv sync --locked
uv run pytest
DATABASE_PATH=dev.db ALERT_API_TOKEN=dev uv run uvicorn app.main:app --reload

To change the schema, append to MIGRATIONS in app/db.py. They run at startup.