# 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

```yaml
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*