# 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

```yaml
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:
```bash
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

```bash
# 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
