Skip to content

ADR-0001: Monitoring & observability stack (Uptime Kuma + Beszel + Diun); backups deferred

  • Status: Accepted
  • Date: 2026-07-14

Context

The homelab had grown to ~20 stacks with no monitoring, alerting, update-awareness, or backups. We needed, in priority order: (1) know when a service is down, (2) see host/container resource use, (3) know when a pinned image has an update, (4) protect irreplaceable data. This is a single-host homelab run by one admin — not a fleet — so operational simplicity outweighs enterprise features.

Decision

Deploy three complementary, lightweight tools rather than a heavier metrics platform:

  • Uptime Kuma (up.fmm.house) — availability of every *.fmm.house service.
  • Beszel (bz.fmm.house) — host + per-container metrics (the btop-style view); hub + a local agent that auto-registers via a universal token (agent connects out to the hub).
  • Diun (no UI) — watches all container images and fans notifications to two channels: a Matrix room ("Homelab Updates", bot @diun) and MQTT docker/diun → HA automation → phone push. This reuses existing infra (Matrix, mosquitto, HA) instead of adding a push service.

Also add a Docker HEALTHCHECK to ~every container (see ADR-0004).

Backups are explicitly out of scope here and deferred to a separate effort with a dedicated off-box target (recommended: restic + Backrest) — you don't colocate backups with the data they protect.

Alternatives considered

  • Grafana + Prometheus + node_exporter/cAdvisor — the industrial standard, but heavier to run/maintain than a single-host lab needs. Deferred; adopt later if historical dashboards are wanted. Beszel covers the "what's it doing right now" need.
  • Netdata / Glances for the btop view — Beszel already provides it, so not added.
  • What's-Up-Docker vs Diun — Diun chosen: config-file driven and notify-only, which fits our hand-pinned-image, infra-as-code style (no auto-updates).
  • Kopia / Duplicati for backups — restic + Backrest preferred, but the whole backup piece is deferred regardless.

Consequences

  • Green availability + resource visibility; update alerts land on phone and in Matrix.
  • Uptime Kuma stores state in SQLite only (no PostgreSQL support upstream) and has no REST API — monitors are managed via its UI or by editing kuma.db + restart.
  • Diun digest-watches by default; for "a newer version tag exists" alerts on a pinned image, add label diun.watch_repo=true to that service.
  • Backups remain the top open gap. Revisit as a follow-up ADR when implemented.
  • Details & runbook: docs/runbooks/monitoring.md.