Uptime Kuma: What It Is, Core Features, and Setup Guide

What it is

Uptime Kuma is an open-source, self-hosted monitoring application created by developer Louis Lam. In system administration and web development, self-hosting refers to installing and running an application on your own local computer, home lab, or private virtual server, rather than relying on a commercial third-party cloud provider to host and manage the service for you.

According to the project repository, the motivation behind Uptime Kuma arose when the creator was searching for a self-hosted uptime tracking tool similar to commercial services such as Uptime Robot. An existing open-source tool, Statping, was considered during that search, but it had become unstable and was no longer actively maintained. In response, the author set out to develop a modern alternative with an emphasis on creating a responsive and visually polished interface.

The application was built using modern web development technologies. On the user interface side, it incorporates Vue 3, Vite.js, and Bootstrap 5 styling. Rather than using a conventional REST API (where a web client repeatedly makes individual HTTP requests to fetch server state), Uptime Kuma was engineered as a Single Page Application (SPA) communicating over WebSockets. A Single Page Application loads a single web page and updates the displayed information dynamically, while WebSockets establish a persistent, bidirectional communication channel between the user’s browser and the server. This design allows real-time metric updates to flow directly to the screen without requiring manual page reloads.

For those who wish to observe how the interface operates before setting up an instance, the project provides a temporary live demonstration hosted in Frankfurt, Germany, accessible at the project demo link (https://demo.kuma.pet/start-demo). This demo environment automatically deletes all recorded data after ten minutes and is funded through community sponsorships.

What it can do

Uptime Kuma provides capabilities for tracking the health, availability, and response characteristics of a wide variety of network services and online infrastructure. According to the project README, the software provides a fancy, reactive, and fast user interface and user experience, complete with both light and dark visual presentation modes.

The monitoring engine supports a broad selection of check types and protocols:

• HTTP and HTTPS Endpoints: Monitors standard website URLs for connectivity and valid response codes. Beyond basic availability, administrators can configure keyword searches to confirm that expected text appears in the returned page body, or perform JSON queries to evaluate specific attributes within structured API responses.
• TCP Connections: Evaluates connectivity over Transmission Control Protocol (TCP), verifying whether a designated network port on a remote server accepts connections.
• Ping Monitoring: Sends network ping requests to verify whether a target host responds across the network, logging response times over an interactive ping chart.
• DNS Records: Checks Domain Name System (DNS) records to ensure domain names resolve correctly to expected IP addresses or record entries.
• WebSocket Connections: Connects to WebSocket endpoints to verify persistent live-data sockets remain open and responsive.
• Push Monitors: Provides a passive “heartbeat” mechanism where external background jobs, automated scripts, or scheduled tasks send an HTTP request to Uptime Kuma. If an expected check-in does not arrive within the specified schedule, an alert is triggered.
• Game Servers and Containers: Includes dedicated monitoring support for Steam game servers as well as local Docker containers.

The application allows check intervals as rapid as twenty seconds. In addition to uptime, it extracts and displays SSL/TLS certificate information, assisting administrators in tracking certificate validity and expiration dates to avoid unexpected service disruptions.

To share uptime metrics with external audiences or internal teams, Uptime Kuma supports creating multiple distinct status pages. Administrators can customize these pages and map them to dedicated domain names.

When an incident occurs or a service recovers, Uptime Kuma can route notifications across more than ninety supported services. Examples documented in the repository include Telegram, Discord, Gotify, Slack, Pushover, and standard email via SMTP.

For operational security and administration, the software includes built-in support for Two-Factor Authentication (2FA), an added layer of account security requiring a secondary verification code during login. It also provides proxy support, allowing monitoring requests to route through intermediary proxy servers when necessary, and features multi-language localization coordinated by community contributors through the Weblate platform.

How to get started

Uptime Kuma provides several installation paths depending on your infrastructure preferences. The primary deployment options documented by the project are Docker Compose, a standalone Docker command, and a non-containerized setup using Node.js and PM2.

Docker Compose

Using Docker Compose is a streamlined way to launch the service. To install with this method, create a dedicated directory, retrieve the official configuration file, and start the container:

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

Once the container starts, Uptime Kuma listens on port 3001 across all network interfaces, making it accessible in a web browser at http://localhost:3001 or http://your-ip:3001.

The documentation emphasizes an important storage warning: network file systems such as NFS (Network File System) are not supported. Storage directories must be mapped to local disks or native local Docker volumes to prevent database issues.

Standalone Docker Command

If you prefer running a single Docker CLI command rather than using Docker Compose, the container can be launched with the following command:

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

By default, this exposes port 3001 on all network interfaces. If you want to limit access strictly to the local host machine, the port binding can be adjusted:

docker run ... -p 127.0.0.1:3001:3001 ...

Non-Docker Installation

For environments where containerization is not used, Uptime Kuma can be installed directly on the host operating system. This method requires Git, Node.js version 20.4 or higher, and PM2 (a production process manager that keeps Node.js applications running continuously in the background).

To clone and set up the project:

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

After starting the process, the web dashboard becomes accessible on port 3001. For administrators managing the process through PM2, the project documents additional operational commands:

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

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

For advanced deployments requiring reverse proxies or specific network routing, detailed setup guides and update procedures are maintained within the project wiki documentation (https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install and https://github.com/louislam/uptime-kuma/wiki/%F0%9F%86%99-How-to-Update).

Pricing and requirements

Uptime Kuma is open-source software distributed under the MIT license, as recorded in the project repository metadata. Specific details regarding any commercial offerings, sponsorships, or official hosting plans are subject to the project’s official website at uptime.kuma.pet.

Deploying and maintaining the software requires meeting specific platform and runtime criteria:

• Supported Operating Systems: Major Linux distributions such as Debian, Ubuntu, Fedora, and ArchLinux are supported. For Windows environments, the software supports 64-bit editions of Windows 10, Windows Server 2012 R2, or higher versions.
• Unsupported Environments: The project documentation explicitly notes that BSD-based systems (FreeBSD, OpenBSD, NetBSD) are not supported. In addition, containerless hosting environments such as Replit and Heroku are listed as unsupported.
• Runtime and Tooling: For non-Docker installations, the system requires Node.js version 20.4 or higher, the Git version control system, and PM2 alongside the pm2-logrotate plugin for background execution.
• Filesystem Constraints: File storage must reside on local filesystems or standard local volumes; Network File System (NFS) storage mounts are explicitly unsupported.

Who it is for

Uptime Kuma is suited for system administrators, DevOps practitioners, homelab operators, and web developers who want full control over their infrastructure monitoring without depending on an external SaaS provider. Because the software runs entirely on the host infrastructure, it accommodates monitoring private internal networks, local Docker containers, and secured servers that cannot be reached by public cloud scanners.

The application is also suitable for organizations needing public or client-facing communication tools. Teams that want to display real-time availability across dedicated domain names can configure distinct status pages for customers or internal stakeholders.

Finally, Uptime Kuma appeals to open-source contributors and community managers. Users can participate in testing pull requests, evaluating beta releases, contributing localized translations through Weblate, or seeking peer support on community forums like the project subreddit (r/UptimeKuma) and GitHub Issues.

Alternatives

• Gatus serves as an alternative service monitoring tool.
• Healthchecks is another available option for tracking system health.

Sources

• https://github.com/louislam/uptime-kuma
• https://github.com/TwiN/gatus
• https://github.com/healthchecks/healthchecks