One Open Source Project a Day (No. 261): Uptime Kuma — A 90k-Star Self-Hosted Monitoring Tool, One Docker Command to Replace Uptime Robot

Uptime Kuma is a self-hosted monitoring tool from louislam, with a polished UI and an easy setup. It supports ten monitor types including HTTP(s), TCP, keyword, JSON query, Ping, DNS, Push, and Docker containers, checks as often as every 20 seconds, ships with more than 90 notification services, and offers status pages that can be mapped to your own domain. One docker run command is enough to deploy. MIT License, about 94k Stars.

·8 min read·AI Engineering
Open SourceUptime KumaMonitoringSelf-HostedDockerStatus PageOps

Introduction

"A fancy self-hosted monitoring tool."

This is the 261st article in the "One Open Source Project a Day" series. Today's project is louislam's Uptime Kuma.

Personal sites, home services, a small team's internal systems: they all share one plain need, which is to know right away when something goes down. Commercial services such as Uptime Robot can do it, but free tiers are limited and your data lives with someone else. Uptime Kuma's answer is to run one yourself on a machine you control, with a good-looking UI and simple setup, pushing a message to Telegram or a similar channel when something fails.

It is one of the most popular ops projects on GitHub, with about 94k Stars. This article follows the README and repo metadata; I did not deploy it or run these commands.

What You Will Learn

  • What Uptime Kuma can and cannot monitor
  • Several ways to deploy it, with Docker or Node directly, and the limits that are easy to trip over
  • The two most used features: status pages and notification channels
  • The project's positioning, its limits, and when not to use it

Prerequisites

  • Basic Docker use, or the ability to install Node.js on Linux
  • A basic idea of "monitoring, alerting, and status pages"
  • Optional: having used Uptime Robot or a similar service

Project Background

What It Is

The author is plain about it in the README: he wanted a replacement for Uptime Robot, found statping unstable and no longer maintained, and so wrote his own. Side goals included building a good-looking UI, learning Vue 3 and vite.js, showing off Bootstrap 5, using WebSocket with a single-page app instead of traditional REST, and publishing his first Docker Hub image.

Project Stats

  • ⭐ GitHub Stars: about 93,609
  • 🍴 Forks: about 8,706
  • 💻 Language: JavaScript
  • 📅 Created: 2021-07-03; last pushed 2026-11-13; latest release 2.5.11 (2026-11-12)
  • 📄 License: MIT
  • 👤 Author: louislam
  • 🌐 Website: uptime.kuma.pet

What It Does

The Problem It Solves

Without monitoring:
  A site or service goes down → you find out when users complain
  ↑ slow diagnosis, bigger losses
 
With Uptime Kuma:
  Check your services on a schedule → alert when they are unreachable
  ↓ messages go to the channels you already use
  ↑ and users get a public status page

Core Capabilities

CapabilityDescription
Monitor typesHTTP(s), TCP, HTTP(s) keyword, HTTP(s) JSON query, Websocket, Ping, DNS record, Push, Steam game server, Docker container
Check intervalAs short as every 20 seconds
NotificationsTelegram, Discord, Gotify, Slack, Pushover, email (SMTP), and more, over 90 in total
Status pagesMultiple pages, mappable to specific domains
OtherReactive, fast UI, multiple languages, ping chart, certificate info, proxy support, two-factor authentication (2FA)

Quick Start

Option 1: Docker Compose

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

Option 2: A single Docker command

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

Both serve on port 3001 and listen on all network interfaces by default. To limit access to the local machine, change the port mapping to -p 127.0.0.1:3001:3001.

Option 3: Without Docker

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup
 
# Try it first
node server/server.js
 
# Recommended: run in the background with PM2
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma

Handy PM2 commands: pm2 monit to view console output, and pm2 startup && pm2 save to start at boot.

Requirements

  • Node.js 20.4 or later
  • Git
  • pm2 for background running

Supported platforms

  • Major Linux distributions (Debian, Ubuntu, Fedora, ArchLinux, and others)
  • Windows 10 (x64) or Windows Server 2012 R2 (x64) and newer
  • Not supported: FreeBSD, OpenBSD, NetBSD, Replit, Heroku

To see it first, use the official demo site; its data is wiped after 10 minutes.

A Deeper Look

Usage Details Worth Knowing

1. Choose the right monitor type to catch real failures

  • To test only whether a port is reachable, TCP is enough
  • If the site opens but the page content is broken, use an HTTP(s) keyword monitor to check that a certain word is on the page
  • If an API returns 200 but the data is wrong, use a JSON query monitor to check a field in the response
  • To know whether scheduled jobs (backups, syncs) ran on time, use a Push monitor: the job calls an address provided by Uptime Kuma when it finishes, and if nothing arrives for a while, you get an alert
  • If a service runs in a container, you can monitor the Docker container's status directly

2. Status pages

A status page is for "other people": pick a few monitors, put them on a public page, and optionally bind your own domain. For personal projects and small teams, this is much less work than building one yourself.

3. Where data lives

-v uptime-kuma:/app/data in the Docker command is the data volume. The README specifically warns: network file systems such as NFS are not supported, so map to a local directory or volume, or you may run into problems.

4. Notification channels

The README says there are over 90. The common ones, Telegram, Discord, Slack, and email, are in there. I did not check each channel's configuration fields one by one; go by the fields shown in the UI when you set one up.

The Project's Technical Choices

The README's own account shows a few choices by the author: Vue 3 with vite.js on the front end, Bootstrap 5 for styling, WebSocket between front and back end, and a single-page app instead of a traditional REST interface. Translations are done collaboratively through Weblate, with files under src/lang.

Limits and Cautions

Stated in the README:

  1. Network file systems (such as NFS) are not supported for the data directory
  2. The author does not give support by email; use GitHub Issues or r/UptimeKuma
  3. The author says many PRs are waiting and he lacks time to test them all
  4. uptimekuma.co is not the official site and is not controlled by the project

Two more points are my own judgment:

  • It is a single-instance tool: the monitoring runs on one of your machines, and if that machine or its network has problems, the monitoring fails with it. For important cases, add an external probe too, or deploy Uptime Kuma on a different network from the services it watches
  • Its depth is limited: it is good at availability checks ("is it up, is it fast"), not metrics and tracing like Prometheus and Grafana, so do not expect it to replace those

I also did not check what changed incompatibly between 1.x and 2.x; read the release notes before upgrading from an older version.

Sponsorship and Contributing

The project is funded through Open Collective and GitHub Sponsors, and the README names a special sponsor, Atlas Cloud, which gives USD 400 per month for use of its AI models. Welcome contributions include PRs, testing PRs and betas, bug reports, feature requests, translations, and grammar fixes; upcoming work is tracked in GitHub milestones.

Project Links and Resources

Summary

Key Takeaways

  1. Clear positioning: self-hosted availability monitoring, an open-source alternative to Uptime Robot
  2. Enough features: ten monitor types, checks as often as every 20 seconds, over 90 notification services, and status pages you can bind to a domain
  3. Simple deployment: one docker run, or Node with PM2
  4. Clear boundaries: no NFS, not a replacement for metrics monitoring, and a single instance can itself fail
  5. Limited maintainer bandwidth: PRs queue up, and support runs through Issues and the community only

Who This Is For

  • Developers with personal sites or self-built services who want low-cost monitoring
  • Small teams monitoring the availability of internal services
  • Anyone who wants a public status page for a product

Suggested First Steps

Click around the official demo first to get familiar with monitor types and notification settings. Then install one on a small machine with docker run, monitor one of your own sites, set up Telegram or email notifications, and deliberately stop the service to confirm the alert arrives. Once it works, consider binding a status page to your own domain.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage

← Back to Blog