Skip to content

2026-08-18 — Sepia Uptime Kuma monitoring

Summary

Added Uptime Kuma to sepia using the established shuttle pattern: a pinned Docker deployment with read-only Docker socket access, shared service networks, Docker health monitors for all relevant containers, and HTTP checks for the services where an application-level check provides better signal than container state alone.

Context

Shuttle already uses Uptime Kuma as its Docker-environment monitor. The sepia host had no Kuma deployment or monitor coverage. The implementation intentionally follows the shuttle layout while using only services that exist on sepia.

Changes

Uptime Kuma deployment

  • Files: /opt/compose.uptime.yaml, /opt/compose.yaml
  • What: Added louislam/uptime-kuma:2.4.0 as uptime, persisted at /opt/uptime, with read-only Docker socket access and membership of the frontend, backend, storage, and monitoring networks.
  • Compose: Included the service from /opt/compose.yaml.

Monitor provisioning

  • File: /opt/scripts/provision-sepia-uptime.py
  • What: Added an idempotent SQLite provisioning script that creates the local Docker host, Docker and Application groups, and the monitor inventory.
  • Docker monitors: 18 containers: homeassistant, docs, keepassxc, rclone-webdav, dsmr, dsmrdb, esphome, influxdb, grafana, seafile-mysql, timescaledb, seafile-redis, blocky, caddy, collectd, seafile-server, borgmatic, and uptime.
  • HTTP monitors: uptime-http, docs-http, grafana-api, dsmr-http, influxdb-health, and seafile-http.
  • Not added: File Browser is not running on sepia. Blocky is on a network not shared with Kuma, so its application-level check was omitted; its Docker monitor remains active.
  • Credentials: No credentials or .env files are stored in Kuma configuration.

Decisions

  • Use the same Kuma image version as shuttle (2.4.0) rather than introducing a version difference.
  • Use Docker monitors as the baseline because they cover container health and restart state without duplicating credentials.
  • Add HTTP checks only where they test an application endpoint or protocol that Docker health alone cannot validate.
  • Treat running containers without a Docker healthcheck (keepassxc, rclone-webdav, and borgmatic) as UP while they are running; the monitor message explicitly identifies this weaker signal.
  • Exclude host-network services from synthetic HTTP checks when no stable in-network target exists; they remain covered by Docker monitors.

Verification

  • docker compose -f /opt/compose.yaml config completed successfully before deployment.
  • uptime is running louislam/uptime-kuma:2.4.0 and its Docker healthcheck is healthy.
  • The Kuma database contains 24 monitors: 18 Docker monitors and 6 HTTP monitors, plus the two groups.
  • All 24 monitor heartbeats are UP:
  • Docker monitors report healthy, or the explicit running-without-healthcheck UP message for keepassxc, rclone-webdav, and borgmatic.
  • All HTTP monitors report 200 - OK.
  • The provisioning script was run after deployment and is idempotent; a second run did not create duplicates.
  • Existing unrelated working-tree changes in compose.homeassistant.yaml, homeassistant/mqtt.yaml, homeassistant/.cache/, and homeassistant/www/ were left untouched.

Access

The initial Kuma account is user. A bootstrap password was generated during setup and should be replaced through the Kuma UI after first login.

Generated: 2026-08-18

Subdomain

  • Added the unprotected Caddy route uptime.uitgeest.veenboer.xyz to the sepia Caddyfile.
  • The route proxies to the uptime:3001 Docker service and uses the same unprotected-route pattern as the other internally authenticated applications.
  • Caddy configuration validation and reload completed successfully.
  • DNS resolves uptime.uitgeest.veenboer.xyz through the existing uitgeest.veenboer.xyz DNS setup.
  • An external HTTPS request returns Uptime Kuma's /dashboard redirect, confirming that Caddy no longer adds Basic Auth or Authentik authentication.