homelab-optimized/docs/services/individual/uptime-kuma.md

Uptime Kuma

Self-hosted uptime monitoring with a clean dashboard, multi-type monitors, and ntfy/Signal notifications.

Overview

Property	Value
Host	Raspberry Pi 5 (100.77.151.40)
Compose file	hosts/edge/rpi5-vish/uptime-kuma.yaml
Web UI	http://100.77.151.40:3001
Docker image	louislam/uptime-kuma:latest
Network mode	host
Data directory	/home/vish/docker/kuma/data

Current compose config

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    network_mode: host
    volumes:
      - /home/vish/docker/kuma/data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

The docker.sock mount (read-only) enables the Docker container monitor type for pi5-local containers.

---

Docker Container Monitoring

Kuma supports a "Docker Container" monitor type that checks container state directly via the Docker API rather than via HTTP/TCP.

How it works

• Kuma connects to a registered Docker Host (socket or TCP)
• Polls the Docker daemon and checks if the named container is in running state
• Reports the container's healthcheck status in the message field (healthy, unhealthy, starting, or blank if no healthcheck)
• Up/down is based purely on running vs not-running — not on service-level health

Docker Hosts configured

Name	Type	Connection	Covers
pi5-local	socket	/var/run/docker.sock	pi5 containers only

Docker Container monitors (pi5)

Monitor name	Container	Interval
uptime-kuma (pi5)	uptime-kuma	60s

To add more: in the Kuma UI, create a new monitor → type "Docker Container" → select pi5-local → enter the container name.

---

Socket vs TCP — Which to Use

Socket (what is configured)

• Kuma reads /var/run/docker.sock directly on the same host
• Only works for containers on the same host as Kuma (pi5)
• No network exposure, no TLS config required
• Mount as :ro (read-only) — sufficient for monitoring

TCP (remote Docker daemon)

• Requires exposing Docker daemon on port 2375 (plain) or 2376 (TLS) on each remote host
• On Synology DSM, this is non-trivial to configure and secure
• Exposes a full root-equivalent interface to the Docker daemon over the network
• Kuma's own docs warn against exposing Kuma to the internet when TCP is enabled
• Not recommended for this homelab — the security tradeoff is not worth it for container state checks alone

Why TCP is not needed here

Portainer BE already provides container state visibility across all hosts via its agent model (Atlantis, Calypso, Concord NUC, Homelab VM, RPi5). Opening Docker TCP on each host just to duplicate that in Kuma adds attack surface without adding meaningful monitoring capability.

For remote hosts, HTTP/TCP monitors in Kuma are a better fit — they test actual service availability rather than just container running state.

When Docker socket monitoring is useful

• Containers with no HTTP endpoint (workers, agents, background jobs)
• Catching containers that have crashed before restart: unless-stopped kicks back in
• A lightweight "is it even running" layer alongside existing HTTP checks

Good candidates on pi5: dozzle-agent, scrutiny-collector, diun (none of these expose an REDACTED_APP_PASSWORD can check).

---

Monitor Types in Use

Type	Use case
HTTP(s)	Web services, APIs — checks response code and optionally keyword
TCP	Non-HTTP services (databases, game servers, custom ports)
Ping	Network-level host reachability
Docker Container	Container running state (pi5-local only, via socket)

---

Notifications

Configured notification channels:

• ntfy — push notifications for status changes
• Signal — via signal-cli-rest-api on homelab-vm (100.67.40.126:8080)

---

Database

Kuma stores all configuration in SQLite at /home/vish/docker/kuma/data/kuma.db.

Key tables: monitor, docker_host, heartbeat, notification, user

To inspect monitors directly:

ssh pi-5 "docker exec uptime-kuma node -e \"
const sqlite3 = require('@louislam/sqlite3');
const db = new sqlite3.Database('/app/data/kuma.db');
db.all('SELECT id,name,type,active FROM monitor', (e,rows) => { console.log(JSON.stringify(rows,null,2)); db.close(); });
\""

Note: changes to the DB take effect after a container restart — Kuma caches monitors in memory.

---

Useful Commands

# View logs
ssh pi-5 "docker logs uptime-kuma --tail 50"

# Restart
ssh pi-5 "docker restart uptime-kuma"

# Check socket is mounted
ssh pi-5 "docker inspect uptime-kuma | python3 -c \"import sys,json; print([c for c in json.load(sys.stdin)[0]['HostConfig']['Binds']])\""

---

Related docs

• docs/admin/monitoring.md — overall monitoring strategy
• hosts/edge/rpi5-vish/uptime-kuma.yaml — compose file