Uptime Kuma: Self-Hosted Uptime Monitoring Tool

What Uptime Kuma is

Uptime Kuma is a self-hosted monitoring tool that checks whether websites, services and hosts are reachable, records response times, sends alerts when something goes down and publishes public status pages. The README describes it simply as "an easy-to-use self-hosted monitoring tool". You install it on a machine you control, open a web dashboard, add monitors through the UI and pick where notifications should go. Checks run from the Uptime Kuma host or container itself: the troubleshooting page's first step for a monitor that reports DOWN while the service is reachable is to open a shell in the container and test with curl and ping, noting that the Docker network type decides what the container can reach.

The project's stated motivation explains its shape. The author writes that he "was looking for a self-hosted monitoring tool like "Uptime Robot", but it is hard to find a suitable one". Other listed goals include building "a fancy UI" and trying "to use WebSocket with SPA instead of a REST API". The result is aimed at homelab operators, small teams and anyone who wants uptime checks and a status page without paying for or depending on a hosted service.

The README carries a warning worth repeating: the top search result for the name, uptimekuma.co, is not the official website and is not controlled by the project. The official homepage is uptime.kuma.pet, and the README recommends following the installation guide in the GitHub repository. A temporary live demo hosted in Frankfurt is linked from the README; its data is deleted after 10 minutes.

How it works

One Node.js process, one web UI

Uptime Kuma is a single Node.js application that serves both the backend and the frontend. The contributing guide says the project "was created with vite and is written in vue3", with the backend living in the server directory and communicating "mostly" via websockets. Frontend and backend share one package.json. For production the frontend is compiled into the dist directory and the Express server exposes that directory as the root of the site.

The backend is described as "an express.js server with socket.io integrated". Most server logic lives in socket.io handlers rather than a REST API. Express is used for a narrower set of jobs: redirecting to the dashboard or a status page, serving the built frontend files and serving the internal APIs used by status pages. That design is why the reverse proxy documentation insists on WebSocket support, covered below.

Monitors, heartbeats and notifications

Each monitor type is a module. According to the contributing guide, the core of a monitor is a file under server/monitor-types/ exposing an async check(...) function. On success it sets a heartbeat message and marks the heartbeat UP; on failure it throws an error with an actionable message. Contributors are told never to set the status to DOWN directly "unless you want to explicitly ignore retries", which shows that retry handling sits in shared code above the individual checks. New monitor types are registered in server/uptime-kuma-server.js, and their settings form lives in the shared src/pages/EditMonitor.vue page.

Notification providers follow the same pattern: each one has backend logic under server/notification-providers/ and a Vue component under src/components/notifications/.

Storage

All state lives in a data directory, ./data/ by default and /app/data inside the container. SQLite is the default database. Version 2 added MariaDB as a storage option: the full Docker image ships an embedded MariaDB that the Docker tags page calls "a low-maintenance, durable and performant storage backend", and both image variants can connect to an external MariaDB or MySQL server through the UPTIME_KUMA_DB_* environment variables. Database schema changes are managed as Knex migrations under db/knex_migrations.

Key features

• Many check types. The README lists HTTP(s), TCP, HTTP(s) Keyword, HTTP(s) JSON Query, WebSocket, Ping, DNS Record, Push, Steam Game Server and Docker Containers monitors. The Docker tags page also mentions a "Browser Engine" monitor type that uses Chromium, which is bundled in the full image.
• 20-second intervals. The README lists 20-second check intervals as a feature.
• 90+ notification services. Telegram, Discord, Gotify, Slack, Pushover and Email (SMTP) are named in the README, with a link to more than 90 providers in the source tree. The wiki adds that Uptime Kuma also integrates with Apprise for additional services.
• Multiple status pages with custom domains. You can create several public status pages and map each to its own domain name, so one instance can serve different status pages for different hostnames.
• Scheduled maintenance. Maintenance windows temporarily disable notifications and show a maintenance message on chosen status pages. Schedules can be manual, a single window, a cron expression or recurring by interval, weekday or day of month.
• Badges. Published monitors can be embedded as SVG badges for status, uptime, ping, average response, certificate expiry and response, generated locally using badge-maker in shields.io styles.
• Prometheus metrics. A /metrics endpoint exposes per-monitor metrics such as monitor_response_time and monitor_status, labelled by monitor name, type, URL, hostname and port.
• Certificate info and ping charts. The README lists certificate information and a ping chart among the dashboard features.
• Proxy support and 2FA. The README lists proxy support and two-factor authentication support. Since 2.0.0 a separate NOTIFICATION_PROXY variable can route outgoing notifications through an HTTP, HTTPS or SOCKS proxy.

Getting started

Docker Compose

The README's recommended path downloads the project's Compose file and starts it:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

The Compose file itself is short. It runs the louislam/uptime-kuma:2 image, restarts it unless stopped, maps a local ./data directory into the container and publishes port 3001:

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

Uptime Kuma is then reachable on all network interfaces at port 3001, for example http://localhost:3001. A setup wizard runs on first start with an empty database; the environment variables page says the wizard is skipped when initial admin credentials are supplied through variables marked as available since 3.0.0.

Plain Docker

The single-command equivalent from the README uses a named volume:

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

The README also shows publishing the port as 127.0.0.1:3001:3001 to limit exposure to localhost.

Without Docker

The non-Docker install needs a supported platform, Node.js, Git and optionally pm2 to keep the process running. The README lists major Linux distributions (Debian, Ubuntu, Fedora, Arch Linux and similar) and Windows 10 (x64) or Windows Server 2012 R2 (x64) and later as supported, Node.js 20.4 or newer as a requirement, and FreeBSD, OpenBSD, NetBSD, Replit and Heroku as unsupported. The commands are:

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# Option 1. Try it
node server/server.js

# (Recommended) Option 2. Run in the background using PM2
# Install PM2 if you don't have it:
npm install pm2 -g && pm2 install pm2-logrotate

# Start Server
pm2 start server/server.js --name uptime-kuma

Two more pm2 commands from the README show console output and register the service at boot:

# If you want to see the current console output
pm2 monit

# If you want to add it to startup
pm2 startup && pm2 save

Note that npm run setup is not a generic install step. In the package.json on master it is defined as git checkout 2.5.11 && npm ci --omit dev --no-audit && npm run download-dist, so it pins the checkout to a tagged release and downloads a prebuilt frontend rather than building one locally.

Host, port and data directory

Non-Docker installs can set these in a .env file in the project root or as server arguments. The defaults are host ::, port 3001 and data directory ./data/. TLS can be terminated by Uptime Kuma itself through UPTIME_KUMA_SSL_KEY, UPTIME_KUMA_SSL_CERT and an optional key passphrase, though the wiki recommends putting it behind a reverse proxy for public exposure.

Behind a reverse proxy

Because the dashboard runs over WebSocket, the reverse proxy page stresses that the proxy must forward the Upgrade and Connection headers. Its plain nginx example without SSL is:

server  {
    listen 80;
    # Remove '#' in the next line to enable IPv6
    # listen [::]:80;
    server_name    sub.domain.com;
    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

The same page has variants for nginx with SSL and Certbot, Apache, Nginx Proxy Manager (where you enable "WebSockets Supports"), Caddy via Docker labels and https-portal. If Uptime Kuma is only reachable through the proxy, the wiki suggests enabling Trust Proxy under Settings, Reverse Proxy, so that X-Forwarded-* headers are used and real client IP addresses appear in logs.

Updating

For Compose installs the update guide is to pull and recreate:

cd "<YOUR docker-compose.yml DIRECTORY>"
docker compose pull
docker compose up -d --force-recreate

Plain Docker installs pull the new image and recreate the container on the same volume; non-Docker installs check out the target release tag, reinstall dependencies, download the prebuilt frontend and restart via pm2.

Use cases

• Homelab and self-hosted service monitoring. Track the reachability of web apps, DNS records and Docker containers running at home or on a VPS, with alerts to a chat app such as Telegram or Discord.
• Public status pages for a product. Publish one or more status pages, each on its own domain, show maintenance windows on them, and embed uptime badges in a README or website. The wiki notes that status pages cache results for five minutes and refresh every five minutes, so they suit public communication rather than live operations.
• Containers and game servers. Docker Containers and Steam Game Server are built-in monitor types, so one dashboard can cover container health and community game servers alongside websites. The Docker tags page notes that the Docker monitor needs extra configuration in rootless images because it requires root privileges by default.
• Certificate and API endpoint checks. HTTP keyword and JSON query monitors verify that an endpoint not only responds but returns expected content, while certificate information and the cert-exp badge help track TLS expiry.
• Feeding an existing metrics stack. Teams already running Prometheus can scrape Uptime Kuma's /metrics endpoint and query response times and status alongside other metrics, as in the wiki's example configuration:

- job_name: "uptime"
  scrape_interval: 30s
  scheme: http
  metrics_path: "/metrics"
  static_configs:
      - targets: ["uptime-kuma.url"]
  basic_auth: # Only needed if authentication is enabled (default)
      username: <your user>
      password: <your password>

The metrics endpoint uses HTTP basic authentication by default. API keys, available since 1.21.0, can replace it; the Prometheus API keys page warns that "as soon as you add your first API key, the use of basic authentication for the endpoint will be permanently disabled".

How it compares

The README positions Uptime Kuma against two reference points. The first is Uptime Robot, which it names as the kind of tool it set out to replicate in self-hosted form. The trade-off is the usual hosted-versus-self-hosted one: Uptime Kuma gives you full control over data, check frequency and notification channels at no licence cost, but you run, back up and update it yourself. Because checks run from wherever the instance is hosted, an instance inside the same network as the services it watches cannot report an outage of that network itself, so where it runs matters.

The second is statping, which the README describes as one of the closest self-hosted options at the time but "not stable and no longer maintained".

Uptime Kuma is not a metrics or observability platform in the way Prometheus is. It runs active checks and alerts on reachability, then exposes its results to Prometheus through /metrics. The two are complementary: Prometheus can collect Uptime Kuma's monitor status and response times, while Uptime Kuma handles the check scheduling, notification routing and public status pages.

Things to know before adopting

• Licence. Uptime Kuma is released under the MIT licence, copyright 2021 Louis Lam, which permits commercial use, modification and redistribution with the copyright notice retained.
• Do not put the data directory on NFS. The README states that file systems like NFS are "NOT supported" and asks you to map a local directory or volume. The install wiki explains why: filesystem support for POSIX file locks is required "to avoid SQLite database corruption", and NFS is a common source of file locking problems.
• Backups mean the data directory. The v1-to-v2 migration guide says JSON backup and restore was removed, and that "backing up the data directory is currently the only supported backup method".
• SQLite to MariaDB is not a supported migration. The migration FAQ says moving an existing SQLite database to MariaDB "CANNOT be done directly" and is not officially supported, and that third-party tools such as sqlite3tomysql skip indexes. Choose the backend at install time.
• SQLite concurrency setting. Since 2.3.2, UPTIME_KUMA_SQLITE_SINGLE_CONNECTION defaults to true; setting it to false enables multiple connections but may produce SQLITE_BUSY: database is locked errors.
• v1 to v2 is a breaking upgrade. The migration guide asks you to back up the data directory several times over, warns that aggregating the heartbeat table can take hours on slow hardware or large databases (the author cites about 7 minutes for 20 monitors and 90 days of data), and says an interrupted migration means restoring from backup. v2 also dropped Alpine-based images and Node.js 14, 16 and 18, changed badge duration syntax and moved SMTP templating to LiquidJS. Hosts on Debian or Raspbian Buster should not upgrade because of a libseccomp2 bug.
• Pick Docker tags deliberately. The latest tag is deprecated and still points to v1. The recommended tags are 2 and 2-slim. The slim image is roughly 300 to 400 MB smaller but omits the embedded MariaDB and the bundled Chromium needed for the Browser Engine monitor. SECURITY.md lists 2, 2-slim, next, next-slim, 2-rootless and 2-slim-rootless as supported and v1 tags as unsupported.
• Rootless images have caveats. The wiki warns that some features "may not work as expected": the data directory must be owned by node:node (1000:1000), the Docker monitor needs extra configuration, and rootless images are not recommended for upgrading from v1.
• No subdirectory hosting. The reverse proxy page says Uptime Kuma "does not support a subdirectory" such as /uptimekuma; you need a domain or subdomain. The documented iframe workaround requires UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=true, which the wiki warns exposes the instance to clickjacking.
• Platform support. Linux and Windows are supported for non-Docker installs; the BSDs, Replit and Heroku are not. Docker containers do not get IPv6 out of the box, and the troubleshooting page shows adding an IPv6-enabled network to the Compose file for services reachable only over IPv6.
• Security-relevant defaults. By default the instance refuses to be framed by other origins, and the WebSocket Origin header is checked against the server hostname (UPTIME_KUMA_WS_ORIGIN_CHECK, default cors-like). The NODE_TLS_REJECT_UNAUTHORIZED option ignores all TLS errors, so use it with care. A forgotten admin password is reset with npm run reset-password, inside the container for Docker installs.
• Vulnerability reporting is strict. SECURITY.md says the maintainer no longer checks Security Advisories routinely because of "AI slop reports". Reporters are asked to create an advisory and then raise it, without details, as a human in GitHub Issues. LLM-written reports, scanner output or upstream dependency issues without a proof of concept, and SSRF reports are closed without explanation.
• A 3.0 line is in progress. The package.json on master reports version 3.0.0-beta.0 and declares node >= 26.2.0 in its engines field, against 20.4 for v2, and the environment variables page already documents options marked "since 3.0.0", such as UK_INITIAL_ADMIN_USERNAME and UK_INITIAL_ADMIN_PASSWORD for skipping the setup wizard and a switch to disable the leaked-password check. Check the release notes before tracking beta or next tags.

Project activity

As of November 2026 the repository has about 93,700 stars and roughly 8,700 forks. It was created on 3 July 2021, is written mainly in JavaScript and is licensed under MIT. The most recent push was on 13 November 2026. The wiki's history log tracks the project's growth: on 1 November 2026 it recorded 93,126 stars and about 209 million combined image pulls from Docker Hub and GitHub Container Registry, up from roughly 1,000 stars in August 2021.

The project is maintained by Louis Lam, the copyright holder in the licence, with a contributing guide that distinguishes changes junior maintainers may merge (small bug fixes, translations, new notification providers and monitor types) from new features and breaking changes, which only senior maintainers merge. Planned work is assigned to GitHub milestones, beta releases are published on the releases page, and the wiki has a page on helping to test open pull requests.

Source code and issues are at github.com/louislam/uptime-kuma, the official site is uptime.kuma.pet, and installation, update, reverse proxy and configuration guides live in the project wiki.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/uptime-kuma?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)