Uptime Kuma: know when your homelab is down

The classic homelab monitoring system is a family member saying “the internet is broken again.” It works, but it is slow, loud and has no history. Uptime Kuma gets you the news first, with a graph.

The short answer

Uptime Kuma is a self-hosted monitoring tool with a web interface and an MIT license. It checks web pages, ports, ping targets, DNS records, Docker containers and scheduled jobs, as often as every 20 seconds, and alerts you through more than 90 services such as Telegram, Discord, ntfy or e-mail [1][10]. Setting it up takes minutes. Making it useful takes four decisions: run it somewhere that does not fail together with what it watches, use retries so that a single hiccup does not wake you, route at least one alert somewhere that works without your homelab, and back up its data folder. Our assessment: a monitoring tool that dies with the thing it monitors is a very polite way of saying nothing.

How it works

1. What it checks. The README lists monitoring for HTTP(S), TCP, HTTP(S) keyword, HTTP(S) JSON query, WebSocket, ping, DNS record, push, Steam game servers and Docker containers. It also offers multiple status pages, certificate information, proxy support and two-factor login [1]. Everything is configured in the browser, and the data lands in a single data folder, mounted at /app/data in the container [1][2]. The port (3001 by default) and the data directory can be changed with environment variables [15].
2. Versions and tags on 24 Oct 2026. Version 2 is the current major line. The newest release we found is 2.5.7 from 23 Oct 2026, and the tag 2.5.7 exists on Docker Hub [5][6]. That release fixes a bug where the TCP port monitor ignored retries with SSL/STARTTLS, and it updates the Docker images to Node.js 22.23.4, which rejects a leaked CA certificate that the notes describe [6]. The project’s tag guide marks latest as deprecated and says it still points to version 1. It recommends 2 for the newest 2.x release and offers 2.x.x for an exact version [4]. We pin the exact version in the example below, so that an update is a decision and not a surprise. If you prefer the project’s recommendation, louislam/uptime-kuma:2 is what its own Compose file uses [1]. The -slim variants are smaller, and the rootless images come with warnings, especially for upgrades from version 1 [4].
3. Install. The README gives a Compose file and a single docker run command. The service listens on port 3001 on all interfaces, and the README shows -p 127.0.0.1:3001:3001 to limit exposure to the machine itself [1]. Keep the data on a local disk or a local volume. File systems such as NFS are not supported, because SQLite needs reliable file locking [1][2]. On your first visit you create the admin account, and in version 2 the first screen also asks which database to use. SQLite is the simple choice for a small setup [16]. Create the account at once and switch on two-factor login under Settings, Security [16]. Until an account exists, whoever reaches the address first could claim it.
4. Where to run it. A monitor cannot report its own outage [16]. If Uptime Kuma runs on the same box, the same switch or the same power circuit as what it watches, a power cut or a dead uplink silences the very tool that should tell you. Our assessment: use a small machine on a separate circuit, a cheap VPS, or a device at a friend’s place, and let it watch your home over the internet. Mind the other direction too: if the alert channel itself needs your homelab (a self-hosted chat server, say), the alert dies with the outage. Pick a channel that lives elsewhere, such as e-mail through an outside provider or a hosted messenger [10]. And note what a UPS does here: it buys your homelab minutes, but it does not tell you that the power is gone. Something on the outside has to. We cover that device in “UPS – uninterruptible power supply” (linked under “Related pages”).
5. Monitor types for a homelab. Use ping for the router, switch and hypervisor hosts. Use TCP port monitors for services that are not web pages, such as SSH. Use HTTP(S) monitors for web interfaces and your reverse proxy, with the certificate expiry notification switched on for HTTPS targets [16]. The DNS record monitor checks that a name resolves, which suits the resolver you run at home (see “DNS / name resolution” under “Related pages”). The Docker container monitor needs the Docker socket inside the Uptime Kuma container. The project warns that this gives Uptime Kuma full control over the Docker daemon on the host, that a compromise could therefore spread, and that you should not expose Uptime Kuma to the internet when you use this monitor type [14]. Our assessment: skip that monitor type unless you really need it, and watch containers through their ports instead.
6. Alerts without noise. Add a channel under Settings, Notifications, press Test, and tick the option to enable it by default for new monitors [16]. Native providers include Telegram, Discord, Gotify, Slack, Pushover, e-mail (SMTP), ntfy, Matrix, Signal and a generic webhook [1][10]. Apprise adds further services [9]. Since version 2 the default number of retries for newly created monitors is 0, a change the project made to avoid confusion [7]. That means a single failed check raises an alarm. For most homelab services, set a few retries and a retry interval. With a 60-second interval, three retries and a 60-second retry interval, a real outage alerts after roughly three to four minutes, and a one-off network hiccup stays silent. Those numbers are our example, tune them to your patience. A maintenance window switches notifications off for a period you define and shows a message on the selected status pages [13]. Use it before you reboot the hypervisor, not after.
7. Push monitors: watch the jobs, not just the services. A push monitor works the other way round. Your script calls a URL, and Uptime Kuma raises an alarm when the call does not arrive within the interval [16]. The endpoint is /api/push/<token> with optional query parameters status (up or down, default up), msg (a short message) and ping (a number in milliseconds). The token in the path is the only authentication [11]. The project’s API page adds a caution: the interface is meant mainly for the application itself, and breaking changes between versions can happen without notice, so test it after updates [11]. This is the clean answer to the oldest backup problem: a failed backup job does not complain, it just stays quiet. Make the script report only on success, and the silence becomes your alarm. Our assessment: set the interval a little longer than the schedule.
8. Reverse proxy and status page. Uptime Kuma talks to the browser through WebSockets, so a proxy in front needs the Upgrade and Connection headers. Caddy does that on its own [16]. The project also states that Uptime Kuma does not support a subdirectory such as /uptimekuma, so give it its own (sub)domain [8][16]. If it is reachable only through the proxy, you can enable “Trust Proxy” in the reverse proxy settings so that logs show the real client address [8]. Status pages are meant for the public, cache results for five minutes and refresh every five minutes, so they trail the dashboard [12]. A status page for family and friends is a nice touch. Our assessment: if you publish one, protect the admin side with two-factor login and consider keeping the dashboard reachable only from your LAN or VPN. Our reverse proxy guide covers the general setup (linked under “Related pages”).
9. Backup and update. In version 2 the old JSON backup and restore was removed. According to the project’s migration guide, backing up the data directory is the only supported backup method [7]. A guide by HyperDC stops the container for the copy so the database files are consistent [16]. Updating a Docker setup means pulling the new image and recreating the container with the same volume. With Compose that is docker compose pull and docker compose up -d --force-recreate [3]. A major migration, such as version 1 to 2, rewrites the heartbeat table. The project reports about seven minutes for 20 monitors with 90 days of data, and hours on slow hardware. Do not interrupt it, and restore the backup if it gets interrupted [7]. Our restic guide covers where the copy should go (linked under “Related pages”).

A homelab example

This is a sketch for your own setup, not a report on ours. Names, addresses and tokens are examples.

Assume a small server that is not part of the machines it watches, Docker with the Compose plugin and a reverse proxy that serves status.example.net over HTTPS. Create /opt/uptime-kuma/compose.yaml. It follows the project’s Compose file, with an exact tag instead of :2 and a loopback-only port [1][5]:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.7
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

Start it with docker compose up -d and check docker compose logs --tail 30. The proxy block for Caddy is the project’s own example, status.example.net { reverse_proxy 127.0.0.1:3001 } [8]. Open the site right away, create the admin account and enable two-factor login.

Add a first set of monitors. These are example targets:

Use an interval of 60 seconds and a few retries for the first four. For the backup monitor, copy its push URL and append it to the job, so that it only fires when the backup succeeded:

restic -r /mnt/backup/restic-lokal backup /srv/daten \
  && curl -fsS -m 10 "https://status.example.net/api/push/EXAMPLETOKEN?status=up&msg=OK" > /dev/null

For a nightly job, set the push monitor’s heartbeat interval to something like 26 hours (93,600 seconds), so that one late run does not trigger an alert but a missed night does. To also learn when your homelab itself goes silent, run a second small instance somewhere else and let a cron job on the homelab call its push URL every few minutes. When the calls stop, the outside instance alerts you.

Back up, with the container stopped for a moment:

docker compose stop
tar -czf /srv/backup/uptime-kuma-$(date +%F).tar.gz -C /opt/uptime-kuma compose.yaml data
docker compose start

To update, read the release notes, back up, change the tag in compose.yaml, then run docker compose pull and docker compose up -d --force-recreate [3]. Watch the logs once.

Checklist

• Decide where Uptime Kuma runs, and check that it does not share a machine, switch or power circuit with the services it watches.
• Create the admin account right after the first start, and enable two-factor login.
• Pin an exact image tag such as louislam/uptime-kuma:2.5.7, avoid latest, and read the release notes before each change.
• Keep the data folder on a local disk, never on NFS.
• Publish the port on 127.0.0.1 and put a reverse proxy with HTTPS in front. Check that WebSockets work.
• Set up at least one notification channel that does not depend on your homelab, and press Test.
• Set retries and a retry interval on every monitor, because new monitors in version 2 start with zero retries.
• Add push monitors for backups and other scheduled jobs, and let the script report only on success.
• Create a maintenance window before planned work.
• Back up the data directory regularly, restore it once on another machine, and note the date.
• Avoid the Docker container monitor unless you accept that it exposes the Docker socket.