Your homelab has no idea it's down: Uptime Kuma checks that catch real outages

Who tells you your homelab is down? If the honest answer is "whoever tries to use it first", the book's answer is that Uptime Kuma plus ntfy gets you from silence to useful alerts in an evening. Watch Your Homelab starts its monitoring stack with Uptime Kuma for a simple reason: it answers the first question users ask, "does it work right now?", by doing what a user does, on a timer, and telling you when the answer changes.

The trap: checks that pass while the service is broken

The tempting check is a ping. Ping tells you the guest's network stack is alive. It does not tell you that the web app inside returns a page, that the database behind it answers, or that the certificate has not expired.

The second trap is the default of alerting on the first failed check. One dropped packet at 3 AM and your phone buzzes for a problem that fixed itself two seconds later.

Install it on the monitoring guest

Uptime Kuma 2 is the current major version (2.5 at the time the book was written, October 2026). The book runs it as its own small stack:

# /opt/stacks/uptime-kuma/compose.yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

Start it with docker compose up -d and open port 3001 on the monitoring guest in a browser. The first visit creates the admin account.

Two details matter here:

• Keep ./data on local disk. The project states that network file systems such as NFS are not supported for it.
• Think twice before mounting the Docker socket. Monitoring containers by name needs /var/run/docker.sock, and mounting it gives the container full control of Docker on that host, read-only flag or not. The book's advice: prefer HTTP checks against the service itself, and only add the socket if container state is really what you want to watch.

Pick the monitor type that matches what users experience

Five monitor types cover almost everything in a homelab:

The closer a check is to what a user actually does, the more a green light proves.

The keyword monitor is the one to reach for first. A login page that returns HTTP 200 with a "502 Bad Gateway" body from a reverse proxy passes an HTTP check and fails a keyword check. Pick a word that only appears when the app really works, such as the app's name in the page title.

For HTTPS services, open the monitor's advanced settings and turn on the certificate expiry notification. An expiring certificate is the most predictable outage there is, and the check costs nothing.

Retries: ignore the blip, catch the outage

Each monitor has a heartbeat interval, a retry count and a retry interval. A single failed check is marked pending and retried; the monitor only goes down (and notifies) after the first failure plus all retries fail. The book's homelab default:

One blip produces no alert; a real outage produces one alert about a minute later. For slow-by-nature things, like a NAS spinning up its disks, use a longer interval or a maintenance window rather than more retries.

Groups, tags and maintenance windows

Use groups to mirror how you think about the lab:

• Infrastructure: Proxmox, the firewall, DNS
• Home: Home Assistant, the MQTT broker
• Apps: everything users open

A group shows down when any child is down, so the overview reads at a glance.

Maintenance windows silence notifications for a set of monitors during planned work. Create a recurring one for your monthly update hour, so the planned reboot of the Proxmox host does not page you.

Jobs that run on a schedule: push monitors

For backups and cron jobs, a push monitor turns the check around: Uptime Kuma waits for the job to call a unique URL and goes down if no call arrives in time. For a nightly job, set the interval slightly longer than the schedule (the book uses 25 hours) and call the URL at the end of the job, only on success:

curl -fsS -m 10 --retry 3 "$PUSH?status=up&msg=OK"

With set -e at the top of the script, a failing step ends it before the curl, the heartbeat never arrives, and the monitor goes down. Silence is the failure signal.

Who watches the watcher?

If the monitoring guest dies, its own Uptime Kuma cannot tell you. The book closes that gap with two small moves:

1. Run a second Uptime Kuma on separate hardware (a Raspberry Pi or any always-on machine) with a handful of monitors: the monitoring guest, the Proxmox web interface on port 8006, the router.
2. Add a Push monitor on that second instance and have the monitoring guest call it every minute from cron:

# crontab -e on the monitoring guest
* * * * * curl -fsS -m 10 -o /dev/null http://192.168.10.5:3001/api/push/Wd9Kq2

If the guest, its host or its network goes away, the pushes stop and the second instance alerts. (The address and push token are the book's example lab; use the URL your own push monitor shows.)

Notifications and a status page

Add a notification once under Settings, then Notifications, and attach it to many monitors. The book uses ntfy (its next chapter) and ticks "Default enabled" so new monitors get it automatically.

A status page shows chosen monitors without a login. Add only the family-facing services and it answers "is it just me?" for everyone in the house. Keep it on the internal network: publishing it on the internet tells strangers what you run.

Checklist

• Uptime Kuma 2 running from a Compose file, data on local disk
• A keyword monitor for every web app; TCP or DNS monitors for the rest
• Retries set to 2 with a 20 s retry interval; certificate expiry on for HTTPS
• Groups for Infrastructure, Home and Apps, plus a recurring maintenance window
• Push monitors on every backup and scheduled job
• A second watcher on separate hardware with a dead-man push from the monitoring guest
• One default notification and an internal-only status page

Found this useful? Subscribe on YouTube for the daily video, or follow the RSS feed.