Uptime Kuma on VPS: Setup Guide for Self-hosted Monitoring Tool

Your site goes down in the middle of the night. You find out from a support ticket four hours later. That's exactly the scenario a self-hosted monitoring tool like Uptime Kuma is built to prevent, and if you're still relying on SaaS services that cap your monitors or bill you per check, this guide is worth your time.

Below is everything: what Uptime Kuma actually does, how to install it on a VPS in under 10 minutes, and how to use it properly from day one.

What Uptime Kuma Does and Where It Falls Short

So, what is Uptime Kuma? It's a free, open-source self-hosted monitoring tool that tracks the availability of your websites, APIs, and services in real time. Think of it as a self-hosted alternative to Pingdom or UptimeRobot, except the monitoring data stays on your server, not theirs, and you're not paying per monitor.

What is Uptime Kuma used for beyond basic uptime checks? Quite a bit:

• HTTP/HTTPS monitoring: checks whether your endpoints return the right status codes
• TCP port monitoring: databases, Redis, message queues, anything non-HTTP
• DNS monitoring: catches misconfigured or hijacked records before your users do
• Docker container monitoring: verifies a container is actually running, not just reachable
• Push monitoring: your service sends a heartbeat to Uptime Kuma, instead of the other way around
• Steam game servers, PostgreSQL, MySQL, MQTT, gRPC, and more

Uptime Kuma also supports 90+ notification channels (Telegram, Discord, Slack, email, PagerDuty) and lets you build public-facing status pages you can share with customers.

The honest limitation worth naming: Uptime Kuma checks your services from wherever its host VPS is. If your server is in Frankfurt and your users are in Sydney, your latency readings won't reflect what they experience. The fix is deploying your self-hosted monitoring tool in a region close to your endpoints; more on that in a later section.

Uptime Kuma vs. SaaS Monitoring: When Self-Hosting Makes Sense

SaaS monitoring tools like Pingdom or Datadog charge per monitor, throttle check frequency on lower-tier plans, and keep your infrastructure topology on their servers. For teams with 20+ services, the cost adds up fast.

Switching to Uptime Kuma as your self-hosted monitoring tool changes the equation:

• You pay for the VPS, not per monitor
• Monitoring data never leaves your infrastructure
• Check intervals as low as 20 seconds by default, with 1-second precision available in v2.1.0+ (it'll warn you before you set it that aggressive)
• Full control over alerting, retention, and status page design

The tradeoff? You maintain the server. With Docker, that's realistically five minutes of work a few times a year.

Prerequisites: What You Need Before Setup

Before you learn how to install Uptime Kuma, make sure these are in place:

One thing that catches people: Uptime Kuma does not support NFS-mounted volumes. Map your data directory to local storage only, or SQLite will throw locking errors that are annoying to debug.

For a production-ready self-hosted monitoring tool setup, the general rule is: 1 GB RAM handles around 100 monitors comfortably. For light use (10-30 monitors), even less is fine. If you're planning to run 500+ monitors, Uptime Kuma 2.x supports MariaDB as a backend, so SQLite doesn't have to be your ceiling.

is*hosting's Lite plan (1 CPU / 1 GB) starts at $5.94/month and covers light deployments without overpaying. If you want room to grow or plan to run other services on the same VPS, the Start plan (2 CPU / 2 GB RAM / 30 GB NVMe) at $10.19/month with annual billing is the better pick. Root access and SSH are included on all plans; Docker isn't pre-installed, but you can add it in two minutes.

Before installing anything, this Linux VPS initial setup guide is worth a quick read if you're starting from a fresh server. It covers SSH hardening and basic system configuration.

Install Docker with a single command:

curl -fsSL https://get.docker.com | sh

Then verify:

docker --version
docker compose version

Both should return version numbers. If docker compose errors, install it separately:

sudo apt install docker-compose-plugin -y

How to Install Uptime Kuma on a VPS

With Docker ready, here's how to setup Uptime Kuma step by step. The whole process, Docker installation included, takes under 10 minutes.

Step 1: Create a Working Directory

mkdir uptime-kuma && cd uptime-kuma

Step 2: Write the Compose File

nano compose.yaml

Paste the following:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=UTC

Two lines worth explaining. The ./data:/app/data volume maps Uptime Kuma's SQLite database to your host filesystem, so your monitors, history, and settings survive container restarts and updates. The restart: unless-stopped policy means Docker will restart the container automatically after a crash or reboot, but it respects a manual docker stop during maintenance. If you use restart: always instead, the container will come back up even after you deliberately stopped it, which gets confusing when you're doing upgrades.

Save with Ctrl+O, exit with Ctrl+X.

Step 3: Start the Container

docker compose up -d

Docker pulls the image and launches in the background. Expected output:

[+] Running 2/2
 ✔ Network uptime-kuma_default  Created
 ✔ Container uptime-kuma        Started

Verify it's running:

docker ps

Look for uptime-kuma with status Up. If you want to watch the startup logs in real time (useful if the dashboard doesn't load right away), run:

docker compose logs -f uptime-kuma

This is your first stop for any issue. A successful start ends with something like Listening on 3001.

Open port 3001 in your firewall. This is the single most common reason people get a blank page after a successful docker compose up:

sudo ufw allow 3001/tcp

If you're planning to put a reverse proxy in front of Uptime Kuma (recommended), you can skip this step and leave port 3001 closed to the outside. But if you're accessing it directly by IP, the firewall rule is required.

Step 4: Set Up a Reverse Proxy (Recommended)

Serving Uptime Kuma over plain HTTP on port 3001 works fine for internal use, but if you're exposing a public status page, you want HTTPS. Caddy is the simplest path: it handles TLS from Let's Encrypt automatically with no cert configuration needed.

Install Caddy on the same VPS:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

Then edit /etc/caddy/Caddyfile and replace the default content with:

status.yourdomain.com {
    reverse_proxy localhost:3001
}

Reload Caddy:

sudo systemctl reload caddy

That's it. Caddy fetches the TLS certificate, and Uptime Kuma is now reachable at https://status.yourdomain.com. The domain-to-VPS DNS setup guide covers the A-record configuration if you haven't pointed to your subdomain yet.

Step 5: First Login

In your browser, go to either http://YOUR_SERVER_IP:3001 or your domain if you set up the reverse proxy. Uptime Kuma asks you to create an admin account. Create it and log in.

Before you add a single monitor, go to Settings, then Security, and enable two-factor authentication. Your monitoring dashboard is exposed to the internet and protected by a single password by default. 2FA takes about 60 seconds to configure and removes a real risk.

Common Gotchas (Before You Start Adding Monitors)

These are the things that actually trip people up:

• Blank page after a successful start. Almost always the firewall. Run sudo ufw allow 3001/tcp or check that your cloud provider's security group allows inbound traffic on that port.
• Container status is "Up" but the service is broken. Docker reporting a container as running only means the process started, not that your app inside it is healthy. This is exactly what Uptime Kuma's Docker container monitor is built to catch when you're monitoring other containers. For Uptime Kuma itself, docker compose logs -f uptime-kuma is the fastest way to see what's actually wrong.
• Alert timestamps look wrong. The compose file defaults to TZ=UTCIf your alerts show times that don't match your timezone, update that environment variable to something like TZ=Asia/Kuala_Lumpur and recreate the container.
• Uptime Kuma can't resolve hostnames. This happens sometimes when Docker's internal DNS doesn't inherit your host's resolver. Add explicit DNS servers to the compose file:

    dns:
      - 1.1.1.1
      - 8.8.8.8

• Self-monitoring blind spot. Uptime Kuma can't alert you if the VPS it runs on goes down. For anything production, deploy a second lightweight instance on a different server or in a different region and have each one monitor the other. is*hosting's VPS in 40+ countries makes it straightforward to spin up a second node somewhere geographically separate.

How to Use Uptime Kuma: Monitors, Alerts, and Status Pages

Here's how to use Uptime Kuma from day one without getting lost in the settings.

Adding a monitor

Click "Add New Monitor," select the monitor type (HTTP/HTTPS covers most use cases), enter the URL, and set a check interval. 60 seconds is a practical default; you can go as low as 20 seconds without changing anything. Save it and the monitor appears on the dashboard immediately.

Setting up notifications

Go to Settings, then Notifications. Add your preferred channel: Telegram bot token, Discord webhook, email SMTP, or anything from the 90+ supported integrations. You can assign different notification channels per monitor, so critical services page you on Telegram while low-priority ones just log.

Creating a status page

Go to Settings, then Status Page, then New Status Page. Name it, select which monitors to include, and optionally point it to a custom domain. This is the URL you share proactively with customers, so they can check it themselves before filing a support ticket.

Push Monitors: How Uptime Kuma Push Monitoring Works

Standard monitors have Uptime Kuma reaching out to your service. Push monitors flip it: your service sends a heartbeat to Uptime Kuma, and if that heartbeat stops arriving on schedule, an alert fires.

Uptime Kuma generates a unique push URL per monitor:

https://your-kuma-instance/api/push/<token>?status=up&msg=OK

Your application or cron job hits this URL on an interval. If it misses too many consecutive windows, the monitor flips to "down."

This is particularly valuable for background jobs: a nightly backup script, an ETL pipeline, or any scheduled process where HTTP monitoring would only tell you the server is reachable, not that the job actually ran.

How to Update Uptime Kuma

Updating is where self-hosting often sounds scarier than it is. With Docker Compose, it's two commands:

docker compose pull
docker compose up -d --force-recreate

Docker pulls the latest image, replaces the container, and re-mounts the same data volume. Your monitors, notification settings, and historical data stay exactly as they were.

Before each update, back up the SQLite database:

cp ./data/kuma.db ./data/kuma.db.backup

And if something goes wrong and you need to roll back:

cp ./data/kuma.db.backup ./data/kuma.db

is*hosting VPS plans include free weekly server-level backups, but those are full snapshots. A targeted Uptime Kuma database copy takes two seconds and is faster to restore from if an update goes sideways. Get in the habit of running it before every docker compose pull.

Get It Running Today

Uptime Kuma installs in under 10 minutes on any Linux VPS. As a self-hosted monitoring tool, it has no per-monitor pricing, no data leaving your infrastructure, and no licensing cost. For a DevOps stack or SaaS product with multiple services to watch, it delivers what most paid tools charge $30-100/month for, at the cost of a cheap VPS.

If you need a server, is*hosting's VPS plans start at $5.94/month. The Start plan (2 CPU / 2 GB RAM / 30 GB NVMe) gives you solid headroom for a full Uptime Kuma deployment and then some.

Already self-hosting other tools? The guide on running n8n on a VPS follows the same Docker-based setup pattern. If you're building automation workflows alongside your monitoring stack, n8n and Uptime Kuma pair well on the same server.