Uptime Kuma on a VPS: Docker installation and first working alert

Anyone managing even a single VPS needs to know when a service goes down, not find out from a customer. Uptime Kuma is a free, open-source, self-hosted monitoring tool that runs in a Docker container and installs in minutes. Below are the commands verified against the project's official documentation, for Ubuntu 24.04.

Prerequisites: Docker on Ubuntu 24.04

Ubuntu 24.04 LTS (codename Noble) is one of the versions officially supported by Docker Engine. Before installation, any unofficial Docker packages present on the system should be removed, as they can conflict with the official ones: Docker itself flags docker.io, docker-compose and containerd installed from repositories other than its own as such packages.

The official commands for the Docker apt repository are:

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

After installation, verify that the service is active with sudo systemctl status docker.

Installing Uptime Kuma with Docker Compose

Docker Compose is the method recommended by the project. The commands published in the official GitHub repository are:

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

When complete, Uptime Kuma is accessible at http://localhost:3001 or http://<vps-ip>:3001.

Alternatively, the direct docker run command, also from the official documentation:

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

Two warnings from the documentation not to skip. First: the filesystem hosting the data folder must support POSIX locks to avoid SQLite database corruption; NFS won't work, a local directory or Docker volume must be mapped instead. Second: if the VPS already exposes a reverse proxy, it's worth restricting the port to localhost only with -p 127.0.0.1:3001:3001, letting the proxy handle the public traffic.

For those preferring to avoid Docker, native installation requires Node.js 20.4 or higher, Git and pm2 to keep the process running in the background, on Linux distributions such as Debian, Ubuntu, Fedora or ArchLinux.

First HTTP monitor

On first browser access, the administrator account must be created. From the dashboard, click "Add New Monitor", choose the HTTP(s) type, enter the URL of the service to monitor and the check interval (60 seconds by default, configurable to shorter intervals as well). The project declares a minimum interval of 20 seconds between checks.

Configuring a notification

Uptime Kuma natively supports sending notifications via Telegram, Discord, Slack, Pushover and SMTP email, as well as over 90 additional services through integration with Apprise. Configuration is done from Settings → Notifications, creating a new notification profile and linking it to the monitor. For Telegram you need the bot token and chat ID; for email, the SMTP server parameters (host, port, username, password, sender).

Verifying that the alert actually arrives

Don't trust the green panel. The correct test is to stop the monitored service for a few minutes (for example sudo systemctl stop nginx on the server hosting the monitored site, or block the port with a temporary iptables rule) and check that:

1. Uptime Kuma marks the monitor as down within the set check interval;
2. the notification actually arrives on the configured channel (email or Telegram);
3. the recovery notification also arrives when the service restarts.

If the notification doesn't arrive, the first points to check are the SMTP credentials (port and authentication) or, for Telegram, that the bot has been started in a chat before retrieving the chat ID.

Updates

To update the container, just pull the new image and restart: docker compose pull && docker compose up -d if using Compose, or stop and recreate the container with the new tag if using docker run. The project recommends not upgrading directly from rootless images when going from v1 to v2, as there can be startup issues related to data folder permissions.