Uptime Kuma: monitor all your self-hosted services and get alerted

The more services you self-host, the more you need to know when one breaks — before someone in the house discovers it. Uptime Kuma is a single-container monitor that checks your services every minute and messages you the moment one goes down, and again when it recovers.

Published Nov 17, 2026 · Last updated Nov 18, 2026

Self-hosting has a quiet failure mode: nothing announces a problem. The photo backup stops because a container exited. The media server is fine but its reverse proxy certificate expired. The document archive’s database container is down, so the web page returns an error only when someone actually visits. Uptime Kuma, a free and open-source project inspired by commercial uptime services, replaces discovery-by-accident with discovery-by-alert. It is often the second container people install and the one they end up valuing most, because it watches all the others.

What a monitor actually is

A monitor is one thing to check, how to check it, and how often. Uptime Kuma supports more than thirty monitor types; a home server needs about six of them. An HTTP(s) monitor fetches a URL and expects a healthy status code. An HTTP keyword monitor also requires a word to be present (or absent) in the response, which catches the nasty case of a page that loads but shows an error. A JSON query monitor checks an API health endpoint properly. A TCP port monitor just confirms a port accepts connections — right for databases and other services with no web page. Ping checks a machine is reachable at network level. A Docker container monitor reports whether a container is running, and a Push monitor works in reverse: a backup job or scheduled script pings a special URL when it succeeds, and Kuma alerts you if that ping stops arriving. Kuma also tracks TLS certificate expiry for HTTPS services and warns you before a certificate lapses.

Diagram of Uptime Kuma checking a website, a NAS port, a Docker container and a backup job on a schedule
One Kuma instance, many check types: web, keyword, port, ping, Docker and push monitors cover a whole home server.

What you need

The blind spot, stated honestly: if Kuma runs on the same NAS as everything else and the NAS dies or the home internet drops, Kuma cannot send alerts — the messenger is down with the patient. Serious setups run a second tiny Kuma instance elsewhere (a cheap VPS or a relative’s house) watching the home connection and the main Kuma, or accept the gap knowingly for a home lab. Decide consciously; do not discover it during an outage.

Step-by-step installation

  1. Write the compose file (example below) and start it with docker compose up -d. Kuma listens on port 3001.
  2. Open http://your-server-address:3001 and create the administrator account on first launch. There is no default password to forget to change — the account you create is the account. Make it strong and unique.
  3. Set up notifications before monitors. Go to Settings › Notifications, add your channel (for example an SMTP email, a Telegram bot, or an ntfy topic), and use the Test button. Do not proceed until a test message actually arrives on your phone — an untested alert channel is decoration.
  4. Add your first monitor: New Monitor, type HTTP(s), a friendly name, the service’s URL, and a heartbeat interval of 60 seconds. Set retries to 2 or 3 so a single glitch does not wake you, and make sure your notification channel is ticked for this monitor. Save and watch it turn green.
  5. Add the rest by type: a keyword monitor for any service with a status or login page (require a word that only appears when it works); TCP port monitors for databases and non-web services; a ping monitor for the router and the NAS itself; Docker monitors for your most important containers if you give Kuma access to the Docker socket (read the security note in troubleshooting before doing this).
  6. Add a Push monitor for backups. Create the monitor, copy its push URL, and add a one-line curl call to the end of your backup script so it pings that URL only when the backup completes successfully. Set the interval to slightly longer than your backup schedule. Now a silently failing backup job alerts you by its absence — the most valuable monitor most people never think of.
  7. Tune intervals and retries per importance. Core services: 60 seconds. Nice-to-have services: 5 minutes. Certificates and slow-changing things are tracked automatically. The goal is alerts you trust, which means few enough false alarms that you never mute the channel.
  8. Create a status page under Status Pages: pick the monitors to show, give it a name, and save. You get a clean public-style page — handy as a household “is it me or is it down?” link, and you can keep it on the local network only if you prefer.
  9. Back up the data volume. Stop-gap measures do not exist here: that one folder is your entire configuration and history. Include it in the same backup routine as your other containers, and after any big setup session, export or copy it once by hand so a known-good version exists.

A concrete Docker Compose example

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      # Optional, for Docker container monitors only:
      # - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

Pinning to the major version tag (:1) rather than latest is deliberate: Kuma’s newer major releases can change the database, and you want upgrades to be a decision, not a surprise. The commented-out Docker socket line is left disabled on purpose — mounting the socket gives the container effectively full control of Docker on the host, so enable it only if you actively use Docker monitors and understand that trade-off; a socket proxy with limited permissions is the safer pattern.

Optional: Docker monitors through a socket proxy. A socket proxy is a small extra container that sits between Kuma and the real Docker socket, forwarding only the API calls you explicitly allow. The proxy is the only container that mounts the socket, and it mounts it read-only; Kuma never touches the socket directly. Add a proxy service alongside Kuma, granting just the read access container monitors need:

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: socket-proxy
    environment:
      CONTAINERS: 1   # allow reading container state — all Kuma needs
      POST: 0         # nothing may be created, started or changed
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

Then, in Kuma, go to Settings › Docker Hosts, add a host of type TCP pointing at tcp://socket-proxy:2375, and choose it on your Docker monitors. Be clear-eyed about the limit: a proxy reduces the risk, it does not eliminate it — the proxy itself still holds the socket, and even a read-only view of your containers is information worth protecting. And if you only monitor websites and services, you do not need Docker monitors at all: skip the socket entirely unless you understand what you are granting.

Alert flow diagram from a failed check through retries to notifications by phone push, email and chat, and a recovery message
The alert flow: a check fails, retries confirm it is real, notifications go out — and a second message confirms recovery.

Writing alerts people do not mute

Monitoring fails socially before it fails technically: too many noisy alerts and the channel gets muted, then the real outage is missed. Prevent that with three habits. First, retries — require two or three consecutive failures before alerting, because home networks hiccup. Second, separation — route everything to one calm channel by default and reserve a loud channel (a push service with a persistent alarm, for example) for the two or three services that genuinely matter. Third, maintenance windows — when you are deliberately restarting the NAS or updating containers, pause the affected monitors in Kuma first. An alert that says “down, as expected, because you are updating it” still trains people to ignore alerts.

Common mistakes and troubleshooting

Everything shows down at once

That pattern means the checker, not the services: the host lost network or DNS, or Kuma’s container networking broke. Check whether the NAS itself can resolve and reach those addresses. A ping monitor for your router and one for a public address help separate “service down” from “internet down” at a glance.

HTTPS monitors fail with certificate errors

If a service uses a self-signed or internal certificate, the monitor will (correctly) distrust it. Either give the service a proper certificate through your reverse proxy, or tick “Ignore TLS/SSL error” on that one monitor — consciously, and only on your local network. Also read the certificate-expiry warning Kuma shows; an expired certificate is the most common cause of this symptom in the first place.

Notifications are configured but nothing arrives

Work the chain in order: does the Test button in Settings › Notifications succeed? If not, the provider credentials are wrong — bot tokens, chat IDs and SMTP app passwords are the usual culprits. If the test works but outages stay silent, the channel is probably not ticked on that monitor, or retries have not yet been exhausted, so the monitor has not formally flipped to down.

Kuma itself keeps restarting or loses its data

Almost always the /app/data volume is not actually persistent — a container recreated without the volume starts empty and asks you to create an admin account again. Confirm the volume mapping in your compose file points at a real folder or named volume on storage that survives restarts, and that the folder is writable.

Official documentation and references

Frequently asked questions

How often should monitors check?

Sixty seconds is the sweet spot for important services: fast enough to catch an outage while it still matters, gentle enough to cost nothing. Five minutes is fine for secondary services. Checking every few seconds adds load and alert noise without meaningfully improving a home setup.

Can Uptime Kuma monitor things outside my home?

Yes — it checks any reachable URL, port or address, so it can watch a family website, a VPS, or a relative’s connection you help maintain. Remember the reverse is also true and more important: something outside your home should ideally watch your home, which is the second-instance pattern described above.

Is a status page safe to share?

A status page shows service names, up/down state and response history — no credentials and no access. Many people still keep theirs on the local network or behind their normal remote-access route, and share it only with household members. That is a reasonable default; publishing it publicly is a choice, not a requirement.