ulicraft-server-v1/plan/10-uptime-kuma.md

10 — Uptime Kuma

Distinct from plan/15-mc-status.md: Kuma is the uptime history + alerting backend; mc-status is the live data feed for the landing's server card. Both ping minecraft over mcnet but serve different purposes.

Status monitoring + public status page. Service uptime-kuma (louislam/uptime-kuma:2), web UI on :3001, reached only through caddy at https://status.${BASE_DOMAIN}. Joined to mcnet, so it can probe every other service by its internal container name.

Add a Minecraft monitor

Uptime Kuma ships a built-in Minecraft Server monitor type. It uses the Server List Ping protocol (the same ping the vanilla multiplayer list uses): unauthenticated, so it works fine with ONLINE_MODE=FALSE / ENFORCE_SECURE_PROFILE=FALSE. It reports latency, online/max players, and MOTD.

1. Open https://status.${BASE_DOMAIN} and log in (admin account created on first run).
2. + Add New Monitor.
3. Monitor Type: Minecraft Server.
4. Fill in one of the two probe targets below.
5. Heartbeat Interval: 60 s (fine for a friends' server).
6. Retries: 2, Retry Interval: 30 s — avoids flapping on a GC pause.
7. Save.

Two targets — add both

Monitor	Server	Port	What it proves
MC (internal)	minecraft	25565	The server process is up and accepting pings inside mcnet.
MC (public)	mc.${BASE_DOMAIN}	25565	The full path works: DNS → host firewall → docker port publish → server.

The public monitor is the one that catches "I can't connect" outages — firewall, DNS, or an unpublished port all show red here while the internal monitor stays green. Run both to tell server down apart from path broken.

Internal minecraft resolves because uptime-kuma is on mcnet (the container name is the hostname). It is not routed through caddy — caddy only fronts HTTP vhosts, and MC is raw TCP. Do not point the monitor at caddy or any status. alias.

Notes

• The Minecraft monitor pings TCP 25565; it does not check Simple Voice Chat (24454/udp). Add a separate TCP Port monitor against UDP if you want voice coverage — but Kuma's TCP monitor is TCP-only, so UDP voice has no clean probe; rely on the player report instead.
• Put both MC monitors on the public status page (Settings → Status Pages) so guests can self-check before pinging you.
• Optional companion HTTP monitors for the web stack: https://auth.${BASE_DOMAIN}, https://distribution.${BASE_DOMAIN}, https://${BASE_DOMAIN}, https://files.${BASE_DOMAIN} — a red distribution. here explains client mod-mismatch join failures.
• 1 → 2 upgrade (2026-10-25) — moved off :1, whose image runs Node 18 (EOL, no fix for the Oct 2026 Node CVEs). The first :2 start migrates kuma.db in place (one-way, minutes on a ~140M DB; status page down until it finishes — don't interrupt). Per host: docker compose stop uptime-kuma, tar the kuma_data volume into ./backups/, then pull + up -d uptime-kuma. Rollback = restore the tarball + revert the tag to :1.

An HTTP monitor cannot see an SPA break. It asserts "the server returned 200", which is a much weaker claim than "the app works". files. (Filestash) proved this on 2026-07-14: a bad general.host made every client-side redirect resolve to http://https://files…, so the site was unusable in every browser while / kept returning 200 and the monitor stayed green. If you want a monitor with teeth on a JS app, use Kuma's Keyword type against a string the rendered page must contain, and don't read green as "users can log in".