- Python 76.6%
- Jinja 23%
- Dockerfile 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| .forgejo/workflows | ||
| app | ||
| icon | ||
| n8n | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| Dockerfile | ||
| pyproject.toml | ||
| README.md | ||
| TODO.md | ||
| uv.lock | ||
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.