Skip to main content

Uptime-Kuma

Overview

Uptime-Kuma is a self-hosted uptime monitoring tool that tracks the availability of services and endpoints, sends alerts on downtime, and displays historical uptime statistics. It serves as the primary observability dashboard for the homelab — monitoring both internal services and external URLs.

Access

Type URL Notes
Internal (via Tailscale or LAN direct) Port 3001 on 192.168.1.85
External https://uptime.jeeves5454.ddns.net Internet-facing, protected by Authentik + GeoBlock + CrowdSec

Configuration

Image: louislam/uptime-kuma:2 Compose project: uptime-kuma (managed via Portainer; local file at /home/jeeves/docker/uptime_kuma/docker-compose.yml)

Ports

Port Protocol Purpose
3001 TCP Web UI (also bound to host for direct access)

Traefik Labels

traefik.enable: "true"
traefik.http.routers.uptime.rule: Host(`uptime.jeeves5454.ddns.net`)
traefik.http.routers.uptime.entrypoints: websecure
traefik.http.routers.uptime.tls.certresolver: letsencrypt
traefik.http.routers.uptime.middlewares: authentik-auth@docker,plex-geoblock@file,crowdsec-bouncer@file,uptime-headers
traefik.http.middlewares.uptime-headers.headers.customrequestheaders.X-Forwarded-Proto: https
traefik.http.services.uptime.loadbalancer.server.port: 3001

The uptime-headers middleware injects X-Forwarded-Proto: https — required because Uptime-Kuma needs to know the original scheme for correct redirect handling.

External access is gated behind Authentik SSO, GeoBlock (CA/US/IN), and CrowdSec.

Volumes / Bind Mounts

Host Path Container Path Purpose
/home/jeeves/docker/uptime_kuma/uptime-kuma-data /app/data SQLite DB, config, logs

The data directory stores:

  • kuma.db — SQLite database with monitor config, history, and incidents
  • error.log — Uptime-Kuma application error log

Networks

Network Purpose
traefik-net External Traefik route
uptime-kuma_monitoring Internal per-stack network

Dependencies

  • Traefik on traefik-net for the external HTTPS route
  • Authentik at auth.jeevesconsults.ca for SSO on the external route
  • Network connectivity to all monitored endpoints

Notes / Gotchas

  • Uptime-Kuma v2 uses SQLite. The kuma.db file is the entire state of the service — back it up before any upgrade.
  • The X-Forwarded-Proto header middleware (uptime-headers) is specifically required for Uptime-Kuma to generate correct URLs in status page embeds and notifications.
  • Monitor configurations (which services to check, intervals, notifications) are all stored in the UI and persisted in the SQLite database. There is no YAML-based config file.
  • If Uptime-Kuma reports false positives for internal services, verify that DNS resolution works correctly from within the Uptime-Kuma container on traefik-net.
  • Notification integrations (email, Telegram, Slack, etc.) are configured in the UI under Settings → Notifications.

Last Updated: 2026-06-16

No comments to display

Back to top