# uptimekuma — service uptime monitor (esh-docker-vm)

`louislam/uptime-kuma:latest` on **esh-docker-vm** (`10.0.50.45:3001`). Widget
slug `nethealth` feeds the Uptime Kuma card on the fleet dashboard.

## Why it is in this repo

Adopted 2026-08-18 while cleaning up Homepage. It had run unmanaged on the
host for ~12 months, and its `homepage.group=Apps` label put it in the wrong
dashboard group — where it collided with a *manual* entry for the same
service in the homepage stack's `services.yaml` under Monitoring. Result: two
Uptime Kuma cards on the Main tab, one with the widget and one without.

That is precisely the "never list a labelled container manually" failure the
homepage README warns about, and it survived the 2026-08-17 audit because a
duplicate looks like two plausible cards rather than like an error. The fix
was to keep the label as the single source of truth, move it to `Monitoring`,
and delete the manual block.

## Deviations from house convention (deliberate, not oversights)

The compose was adopted as-run rather than normalised — this was a dashboard
fix, not a rewrite of a service that has been stable for a year:

- `restart: always`, not `unless-stopped`. It revives on Docker daemon start
  even if it was stopped on purpose.
- No `healthcheck:` block. The image ships its own, which is why `docker ps`
  reports `healthy` anyway.

Worth normalising on the next deliberate touch, not worth a restart today.

## The container name

Live container was `45d2522a8cb6_uptime-kuma` — Docker's collision rename from
some past recreate where the old container could not be removed. Recreating
under this compose restores the plain `uptime-kuma` name. Harmless either way.

## Data

All monitor definitions and history live in the named volume
`uptimekuma_uptime-kuma`. **Recreating the container is safe. Deleting that
volume loses every monitor and all history** — there is no config file to
restore from, the state is entirely in the volume's SQLite DB.

## Deploy

```bash
scripts/deploy-stack.sh esh-docker-vm uptimekuma --compose
ssh lkraven@10.0.50.45 'cd /opt/docker/compose/uptimekuma && docker compose up -d'
```

Label changes need a **recreate**, not a restart — Docker only applies labels
when the container is created. After recreating, the Homepage container also
needs a recreate before it re-reads the discovered set.