Uptime Kuma

Last reviewed Aug 22, 2026 · 739 words

Uptime Kuma is the easiest win in self-hosted monitoring: one container, 256 MB of RAM, and fifteen minutes from docker compose up to a dashboard that pings everything you run and messages you when something dies. The tool needs almost no guide. What needs a guide is monitoring strategy — where to run it, what to check, and how to send alerts you will still be reading in six months.

The one rule: don't monitor a box from itself

An Uptime Kuma instance on your main server reports beautifully on everything except the failure you care about most — that server going down, taking the monitor with it. Run it on a different device from the things it watches: the spare Raspberry Pi, a $4/month VPS, the NAS if your services live on a mini PC. The VPS option has a second virtue: it sees your services the way the outside world does, so it catches your ISP, your router, and your reverse proxy, not just your containers. Can't spare a second box? Add a heartbeat-style dead-man check from a free external service so at least "the whole thing is offline" reaches you. The full architecture discussion is in homelab monitoring that works.

Check the service, not the port

Kuma's monitor types form a ladder of usefulness, and most people stop a rung too low:

• Ping proves the machine is powered on. That's all.
• TCP port proves something is listening. A hung app still listens.
• HTTP(S) proves the web server responds. A 200 from an error page passes.
• HTTP with keyword proves the app actually works: check /login for the word "password", or an API health endpoint for "status":"ok". This is the rung to stand on.

Add the specialised types where they fit: DNS checks against your Pi-hole, and certificate-expiry warnings (set to 14 days) on every HTTPS monitor — silent cert expiry is the classic homelab outage. Docker-container monitors are handy but remember they only work where Kuma can reach the Docker socket.

Notifications: one urgent channel, one quiet one

Kuma supports 90+ notification services, which is how people end up with alerts they've learned to ignore. Two channels are enough. Urgent (a push service like ntfy, Pushover, or Telegram): things needing action today — the server is down, a cert expires this week. Quiet (email): everything else. Set retries to 2–3 before a monitor counts as down, so a single dropped packet at 3 a.m. doesn't page you; 60-second intervals with 3 retries means real outages alert within about four minutes, which is the right trade for a homelab. Send a test notification from each channel now, not during your first outage.

Status pages are the underrated feature

Kuma builds public status pages — pick monitors, get a clean page at /status/home you can share. If other people use your services, this converts "is Jellyfin down?" messages into a link. One caution: a status page reveals your internal service names to anyone who can reach it, so if the Kuma instance is internet-facing, keep the page to services those visitors already know exist. More patterns in self-hosted status pages.

Operations notes

Everything — monitors, history, notification configs — lives in one SQLite database in /app/data, so backup means copying one folder (stop the container or use sqlite3 .backup for consistency, per the 3-2-1 rules). Put it behind a reverse proxy with websocket pass-through enabled, because the whole UI is a live socket connection and without it you get a blank page. And know the ceiling: Kuma is single-instance by design, with no clustering and no long-term metrics. Around 50–100 monitors it remains happy; if you want query languages, dashboards, and retention policies, that's Prometheus and Grafana territory, and Kuma still earns its keep alongside them as the simple is-it-up layer.

What I'd do

Kuma on a Pi or cheap VPS, keyword-based HTTP checks on every user-facing service, DNS and cert-expiry monitors, ntfy for urgent plus email for quiet, retries at 3, and a status page for the household. Then stop. The entire point of Uptime Kuma is that monitoring stopped being a project — don't turn it back into one.