Blog
7 min read

What Is Uptime Kuma? A Self-Hosted Uptime Monitor, Explained

Uptime Kuma is a free, open-source, self-hosted uptime monitor with alerts and status pages. What it checks, how to install it with Docker, and where to run it.

Uptime Kuma is a free, open-source monitoring tool you host yourself. It checks your websites and services on a schedule, alerts you through Slack, Discord, Telegram, email and many other channels when something goes down, and can publish a public status page. You run it as a single Docker container with a web dashboard, and it is MIT-licensed.

Think of it as a self-hosted alternative to services like UptimeRobot or Better Stack's uptime checks. The project's GitHub repository is the official home; the README notes that a site ranking high in search results under a similar name is not the official website.

What Uptime Kuma checks

Each thing you watch is a monitor. You pick a type, a target and an interval. According to the README, the built-in types include:

  • HTTP(s): is the URL returning a successful status?
  • HTTP(s) keyword: does the page contain (or not contain) a given string? Useful when your app returns 200 OK with an error page.
  • HTTP(s) JSON query: does a value in a JSON response match what you expect?
  • TCP port: is something listening (a database, a mail server)?
  • Ping: does the host answer ICMP?
  • DNS record: does a record resolve to what you expect?
  • WebSocket
  • Push: the reverse direction. Your cron job or backup script calls a Uptime Kuma URL when it finishes, and Kuma alerts you if the call doesn't arrive in time.
  • Docker container: is a container on a connected Docker host running?
  • Steam game server

Checks can run as often as every 20 seconds. For HTTPS monitors it also shows certificate details, so you can be warned before a certificate expires.

The push monitor is easy to overlook and often the most useful one for small apps. A website being up tells you nothing about whether last night's backup ran.

Notifications

When a monitor changes state (up to down, or back), Kuma sends a notification. The README lists Telegram, Discord, Gotify, Slack, Pushover and email over SMTP, "plus over 90 other services", including generic webhooks. You set up a notification channel once and attach it to as many monitors as you like.

Two settings matter for avoiding alert fatigue:

  • Retries: how many failed checks in a row before the monitor counts as down. One failed request is often a network blip. Note that version 2 changed the default for new monitors from 1 retry to 0, according to the project's v1-to-v2 migration notes, so set this deliberately.
  • Heartbeat interval: how often it checks. Shorter intervals catch problems sooner and generate more noise.

(How to know when your app is down covers alerting you won't learn to ignore.)

Status pages

Uptime Kuma can publish one or more status pages: a public page listing selected monitors with their current state and recent history. You can map a status page to its own domain, for example status.yourapp.com. For a small product this is a cheap way to answer "is it just me?" without anyone emailing you.

Installing Uptime Kuma with Docker

The README gives two ways, both using the louislam/uptime-kuma:2 image.

With Docker Compose, the project's own compose.yaml is:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Save that as compose.yaml and run:

docker compose up -d

Or with a single docker run:

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

Then open http://<your-server>:3001 and create the admin account. Do this straight away: until you do, anyone who reaches the port can claim it.

A few practical notes from the README and wiki:

  • Keep /app/data on local storage. The project says network file systems such as NFS are not supported. All your monitors, history and settings live in that folder, so back it up.
  • Don't expose port 3001 directly if you can avoid it. The README suggests binding to 127.0.0.1:3001:3001 and putting it behind a reverse proxy with HTTPS. Turn on two-factor authentication for the admin account; Kuma supports it.
  • The :2 tag tracks version 2.x. As of November 2026, 2.x is the current stable line (2.5.12 was released on 17 November 2026), and a 3.0.0 beta has just been published with breaking changes. Stay on :2 unless you want to test the beta.

Upgrading from version 1

If you've been running louislam/uptime-kuma:1, version 2 migrates your database on first start. The migration guide warns this can take minutes to hours depending on how much history you have, and must not be interrupted. Stop the container, copy the data folder somewhere safe, then switch the tag. Version 2 also removed JSON backup and restore, so backing up the data directory is now the supported method.

Where to run it: not on the server it watches

This is the mistake almost everyone makes once. If Uptime Kuma runs on the same server as your app and that server goes down, the monitor goes down with it. No check fails, so no alert is sent. You find out from your users.

The same applies to anything that takes out both at once: the same cloud region, the same hosting provider, the same home internet connection.

Good options:

  • A small, cheap VPS at a different provider or region from your production servers. Kuma needs very little. (What is a VPS?)
  • A machine at home or in the office, if its connection is reasonably reliable, for monitoring public endpoints.
  • Running Kuma alongside your app is fine for watching internal things (other containers, a database port) as long as something external watches the server itself.

A common belt-and-braces setup: Uptime Kuma for detailed internal and external checks, plus one free hosted monitor that watches Uptime Kuma's own URL. If Kuma dies, the hosted service tells you.

Uptime Kuma vs hosted uptime monitors

Neither is better across the board.

Uptime Kuma wins when:

  • You want many monitors and short intervals without a per-monitor bill. It's free apart from the server you run it on.
  • You need to check things that aren't public: internal services, TCP ports, Docker containers on your network.
  • You'd like your monitoring data to stay on infrastructure you control.

Hosted monitors win when:

  • You want checks from multiple locations. A single Kuma instance checks from one place, so it can't tell a real outage from a network problem between it and you. Hosted services typically confirm failures from more than one region.
  • You don't want to maintain anything. With Kuma you own updates, backups, TLS, and making sure the monitor itself stays up.
  • You need on-call features such as escalation policies, schedules and incident timelines. Kuma sends notifications; it is not an incident management tool.

For a side project or a small business with a handful of services, Kuma on a separate small server is a solid default. Once you have customers with uptime expectations, a hosted monitor (alone or alongside Kuma) is worth considering. If you're putting a number on those expectations, what 99.9% uptime actually means helps you see how little downtime that allows.

What uptime monitoring doesn't tell you

An HTTP check says the server answered. It doesn't say the checkout works, that background jobs are running, or why something broke. Pair it with a proper health check endpoint that tests your dependencies, push monitors for scheduled jobs, and error monitoring for what users actually hit.

EasySpawn puts production behind a reverse proxy with health checks on a server in Frankfurt; an external monitor like Uptime Kuma, run somewhere else, is a good complement. See how it works or join the waitlist.

Related: How to Know When Your App Is Down (Before Your Users Tell You) · What Is a VPS? Virtual Private Servers Explained for Beginners · What Does 99.9% Uptime Mean? Downtime per Month, Explained · Health Check Endpoints: What /health Should (and Shouldn't) Check

Keep reading