Uptime Kuma is a self-hosted monitoring tool that watches your websites, APIs and servers around the clock and tells you the moment something goes down. It has a clean, fast dashboard, supports 90+ notification channels like Telegram, Discord and email, and even lets you publish a public status page. Best of all, it runs as a single Docker container, so you can have it up and running on Ubuntu in about 15 minutes. This guide walks you through the full setup on Ubuntu 24.04, from installing Docker to adding your first monitor and putting Uptime Kuma behind a secure domain.

Prerequisites

  • An Ubuntu 24.04 (or 22.04) server or VPS with at least 1 GB of RAM and 10 GB of free disk space.
  • A non-root user with sudo privileges.
  • SSH access to the server.
  • (Optional) A domain or subdomain pointing at your server, if you want to access Uptime Kuma over HTTPS instead of an IP address and port.

Step 1: Update the System

Start by refreshing the package index and installing any pending updates. This keeps the Docker installation clean and avoids conflicts with old packages.

sudo apt update && sudo apt upgrade -y

The apt update command refreshes the list of available packages, while apt upgrade -y installs the updates without asking for confirmation at each step.

Step 2: Install Docker Engine

Uptime Kuma is distributed as a Docker image, so Docker Engine is the only real dependency. Install it from Docker's official repository rather than Ubuntu's older packaged version, so you always get current releases and the Compose plugin.

First install the tools needed to add an external repository:

sudo apt install -y ca-certificates curl gnupg

Next, add Docker's official GPG key and repository:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Now install Docker Engine and the Compose plugin:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify both binaries installed correctly:

docker --version
docker compose version

You should see version numbers for both. If you want to run Docker commands without typing sudo every time, add your user to the docker group and log out and back in:

sudo usermod -aG docker $USER
newgrp docker

Step 3: Create the Uptime Kuma Project

Keep the deployment in its own directory so the Compose file and the data volume stay together and are easy to back up later.

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

Create a docker-compose.yml file with the official Uptime Kuma configuration:

nano docker-compose.yml

Paste in the following:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - ./uptime-kuma-data:/app/data
    ports:
      - 3001:3001
    restart: unless-stopped

What this does: the image line pins the stable 1.x release line; the volumes line stores all monitors, settings and history in a local folder so nothing is lost when the container is recreated; ports maps the container's port 3001 to the same port on the host; and restart: unless-stopped brings Uptime Kuma back automatically after a server reboot.

Step 4: Start Uptime Kuma

Pull the image and start the container in the background:

docker compose up -d

Check that the container is running:

docker compose ps
docker logs uptime-kuma --tail 20

The logs should end with a line saying the server is listening on port 3001. If the container shows as running, Uptime Kuma is live.

Step 5: Open the Firewall

If UFW is enabled on your server, allow port 3001 so you can reach the web interface:

sudo ufw allow 3001/tcp
sudo ufw reload

On a cloud VPS, also check your provider's security group or firewall panel and allow inbound TCP traffic on port 3001. You can test the port from your own machine with curl -I http://YOUR_SERVER_IP:3001, which should return an HTTP 200 response.

Step 6: Create the Admin Account

Open http://YOUR_SERVER_IP:3001 in your browser. On first launch, Uptime Kuma asks you to create an administrator account. Pick a strong username and password, and note that there is no password reset by email at this stage, so store the credentials safely.

After logging in you will see an empty dashboard. Click Add New Monitor to create your first check.

Step 7: Add Your First Monitors

For a website, choose monitor type HTTP(s), enter a friendly name, the URL, and a check interval of 60 seconds. Uptime Kuma considers the site up when it returns a 2xx or 3xx status code. You can also add a keyword check so it alerts you if the page loads but the expected text is missing.

Other monitor types worth adding:

  • Ping for servers and network devices that do not run a web service.
  • TCP Port for services like MySQL (3306), SSH (22) or a game server.
  • DNS to confirm a domain still resolves to the right address.
  • Docker Container to watch a container's running state directly.
  • HTTP(s) - Keyword to verify an API returns the expected response body.

Each monitor gets its own uptime percentage, response-time graph and incident history on the dashboard.

Step 8: Set Up Notifications

Monitoring is only useful if you hear about outages. Go to Settings > Notifications and click Setup Notification. Uptime Kuma supports more than 90 providers, including Telegram, Discord, Slack, Pushover and plain SMTP email.

For Telegram, create a bot with BotFather, paste the bot token and your chat ID, and send a test notification. Then edit each monitor and attach the notification channel so alerts fire only for the services you care about. You can set different channels per monitor, for example Telegram for production sites and email for staging.

Step 9: Create a Public Status Page (Optional)

One of Uptime Kuma's best features is the built-in status page, like the ones big SaaS companies run. Go to Status Pages > Add New Status Page, give it a slug such as status, pick the monitors to show, and publish it. Visitors can then see live uptime percentages at http://YOUR_SERVER_IP:3001/status/status without needing a login.

Step 10: Put Uptime Kuma Behind a Domain with HTTPS (Optional but Recommended)

Running the dashboard on an IP address and port is fine for testing, but for daily use a domain with HTTPS is safer and cleaner. Install Nginx and Certbot, then proxy port 3001:

sudo apt install -y nginx certbot python3-certbot-nginx

Create an Nginx server block for your subdomain, for example status.yourdomain.com:

sudo nano /etc/nginx/sites-available/uptime-kuma
server {
    listen 80;
    server_name status.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

The Upgrade and Connection headers matter because Uptime Kuma uses WebSockets for its live dashboard. Enable the site, get a free Let's Encrypt certificate, and test the configuration:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo certbot --nginx -d status.yourdomain.com
sudo nginx -t && sudo systemctl reload nginx

Once this is done, close port 3001 in the firewall and access Uptime Kuma only through the domain. You can also add a simple HTTP basic-auth layer in Nginx if the dashboard should not be public at all.

Verify It Worked

  • The dashboard loads at http://YOUR_SERVER_IP:3001 (or your domain) and you can log in.
  • Each monitor shows a green UP status with a response-time graph after a minute or two.
  • Pause a test monitor or stop a test website briefly and confirm the notification arrives on your Telegram or email within a minute.
  • The status page renders publicly and shows uptime percentages.
  • After a reboot, docker compose ps shows the container back up without manual intervention.

Keeping Uptime Kuma Updated and Backed Up

Uptime Kuma releases updates regularly. Upgrading is a two-command job, and your data survives because it lives in the mounted volume:

cd ~/uptime-kuma
docker compose pull
docker compose up -d

Back up the whole project folder regularly. It contains the Compose file and the uptime-kuma-data directory with the SQLite database holding every monitor, setting and history record:

tar -czf uptime-kuma-backup-$(date +%F).tar.gz ~/uptime-kuma

Store that archive off the server. To restore, unpack it on a fresh machine and run docker compose up -d again.

Common Issues and Fixes

Port 3001 already in use

If Compose fails with a bind error, another service is using the port. Find it with sudo ss -tlnp | grep 3001, then either stop that service or change the left side of the port mapping, for example 3002:3001, and reach the dashboard on port 3002.

Container keeps restarting

Check the logs first: docker logs uptime-kuma --tail 50. The usual causes are a corrupted database after an unclean shutdown or a permissions problem on the data folder. Make sure the uptime-kuma-data directory is owned by your user, not root, and restore from backup if the database is damaged.

Dashboard loads but monitors show "Pending"

A monitor stays pending until its first successful check. Wait one full interval. If it never flips, the container may not be able to reach the target: check DNS resolution inside the container with docker exec uptime-kuma nslookup example.com and confirm outbound traffic is not blocked by the host firewall.

Notifications never arrive

Use the Test button on the notification setup page first. For Telegram, the most common mistake is messaging the bot before it has ever seen your chat ID; send the bot a /start message, then test again. For email, verify the SMTP host, port and credentials in the notification settings.

Live dashboard does not update behind Nginx

If the page loads but graphs freeze, the WebSocket upgrade headers are missing from the Nginx proxy configuration. Add the proxy_set_header Upgrade and proxy_set_header Connection "upgrade" lines shown in Step 10 and reload Nginx.

Conclusion

You now have a self-hosted uptime monitor that rivals paid services: a live dashboard, instant alerts, public status pages and one-command upgrades, all running in a single Docker container on your own Ubuntu server. Start with your most important websites and APIs, attach a notification channel to each, and add monitors as your infrastructure grows. If you need help setting up monitoring, reverse proxies or server hardening for your business, XpertBees handles server setup and ongoing maintenance for you.