Uptime Kuma: Dead-Simple Monitoring for Your Homelab

The first time a homelab service goes down and you don’t notice for three days, you understand why monitoring matters. Uptime Kuma is the tool that fixes this. It watches your services, alerts you the moment something stops responding, and gives you a clean status page you can actually look at.

It’s self-hosted, free, runs in a single Docker container, and takes about ten minutes to set up. There’s no configuration file — everything is done through the web UI. For a homelab, it’s the right tool for the job.

What Uptime Kuma Does

You set up “monitors” — each monitor points at something you want to watch. Uptime Kuma pings it on an interval and records whether it responded. If it stops responding, it sends you a notification.

Monitor types include:

• HTTP(s) — the most common. Checks that a URL returns a successful status code.
• TCP Port — checks that a port is open. Useful for services without HTTP interfaces.
• Ping — ICMP ping to a host. Good for checking if a machine is up at all.
• DNS — checks that a domain resolves to an expected IP.
• Docker Container — checks the running state of a container by name.

For a homelab, you’ll mostly use HTTP and TCP. You’ll add one monitor per service.

Install

mkdir -p /opt/uptime-kuma

Create /opt/uptime-kuma/docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - /opt/uptime-kuma/data:/app/data
    ports:
      - "3001:3001"
    restart: unless-stopped

Start it:

cd /opt/uptime-kuma
docker compose up -d

Open http://YOUR_SERVER_IP:3001 in a browser. The first-time setup asks you to create an admin account. Do that, then you’re in the dashboard.

That’s the whole install. No YAML config files, no environment variables to figure out. The UI handles everything from here.

Adding Your First Monitor

Click Add New Monitor in the upper left. For an HTTP service:

• Monitor Type: HTTP(s)
• Friendly Name: Whatever you want to call it (e.g., “Jellyfin”, “Nginx Proxy Manager”)
• URL: The full URL including port if needed (e.g., http://192.168.1.100:8096)
• Heartbeat Interval: 60 seconds is a reasonable default for homelab use
• Retries: 3 — this means the service has to fail three consecutive checks before it’s marked as down

Click Save. The monitor starts immediately. A green circle means it’s up. Red means it’s down. Gray means it’s never been checked yet (give it a minute).

Add a monitor for each service you care about. For most homelab setups, that’s a dozen or fewer. I have monitors for:

• Each Docker service accessible via Nginx Proxy Manager
• The Proxmox web UI
• My NAS
• External URLs I depend on (the internet at large, my DNS resolver)

Setting Up Notifications

A monitor that can’t alert you is a dashboard you have to remember to check. Set up at least one notification channel before you finish the initial setup.

Go to Settings > Notifications and click Setup Notification. Uptime Kuma supports 90+ notification providers. The ones I’d actually recommend for homelab use:

Telegram — Fastest to set up. Create a Telegram bot via BotFather, get your chat ID, paste both into Uptime Kuma. Notifications hit your phone immediately. [Instructions in the Telegram section below.]

Email (SMTP) — Works with Gmail, Fastmail, your own mail server. Requires SMTP credentials. More setup than Telegram but a natural choice if you’re already managing email.

Slack / Discord — If you have a personal server or workspace already. Webhook-based, takes about two minutes to configure.

Gotify — If you’re self-hosting your own push notifications (another project entirely, but common in homelab setups).

Setting Up Telegram Notifications

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create a bot. You’ll get an API token.
3. Start a conversation with your new bot (click the link BotFather gives you, then Start).
4. Get your chat ID: send any message to the bot, then visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates in a browser. The chat.id field in the JSON response is your chat ID.
5. In Uptime Kuma: Settings > Notifications > Add > Telegram. Paste the token and chat ID.
6. Click Test — you should get a test message immediately.

Once the notification is saved, go back to each of your monitors and add this notification channel to them. Monitors don’t use notifications by default — you have to explicitly assign them.

Status Page

Uptime Kuma lets you publish a status page — a simple public URL that shows the current status of your services. Useful for sharing with household members or just having a clean view you can bookmark.

Go to Status Page in the left sidebar and click New Status Page. Give it a name and a slug (the URL path). Then add your monitors to it — you can choose which ones to expose and group them however you like.

The status page is available at http://YOUR_SERVER_IP:3001/status/YOUR_SLUG. It shows green/red status per service and uptime percentages.

You can also enable the status page publicly if you expose Uptime Kuma via a reverse proxy. I don’t do this for my homelab — there’s no reason to publicize which services I’m running — but it’s there if you want it.

Useful Monitor Settings

A few settings worth adjusting from the defaults:

Heartbeat Interval vs. Retries — 60 second interval with 3 retries means a service has to be down for about 3 minutes before you get alerted. That’s reasonable. If you want faster detection, drop the interval to 30 seconds. If you want fewer false positives on flaky services, raise the retries.

Certificate Expiry Monitoring — On HTTP(s) monitors, there’s a checkbox for monitoring SSL certificate expiry. Turn this on for anything you’ve issued a cert for. You’ll get an alert 14 days before expiry by default, which gives you time to renew.

Expected Status Codes — By default, Uptime Kuma considers any 2xx response as “up.” Some services return 3xx redirects or require authentication and return 401. You can adjust the expected status codes per monitor to match the actual behavior of each service.

Maintenance Windows — If you do scheduled maintenance (updates, reboots), you can schedule a maintenance window in Settings > Maintenance. Uptime Kuma pauses alerting for affected monitors during the window, so you don’t get a flood of notifications when you intentionally take things down.

Keeping It Updated

cd /opt/uptime-kuma
docker compose pull
docker compose up -d

Uptime Kuma uses a pinned major version tag (louislam/uptime-kuma:1) which pulls the latest 1.x release. I update it monthly or when I notice there’s a feature I want. The update process takes about 30 seconds including the brief downtime.

The monitor history and configuration all live in /opt/uptime-kuma/data. Back that directory up alongside your other Docker container configs.

What It Doesn’t Do

Uptime Kuma is a reachability monitor, not an application performance monitor. It tells you whether a service responded — not how slow it was, not what the error was, not whether the database behind it is healthy. For a homelab, that’s usually enough. If you need deeper metrics (CPU, memory, disk, container resource usage), that’s a Grafana + Prometheus project.

Start with Uptime Kuma. It takes ten minutes, covers the most important thing (knowing when something is broken), and you can always add more later.