Uptime Kuma is a self-hosted monitoring tool with a polished web interface. It checks your websites, APIs, ports and certificates every minute and alerts you through dozens of channels when something breaks. Think of it as a free, self-hosted UptimeRobot.

Monitor from somewhere else

A monitor running on the same server as your websites can’t tell you that server is down. Run Uptime Kuma on a separate small VPS — ideally in a different location from what it monitors. It’s light: a few hundred megabytes of RAM covers hundreds of monitors.

1. Install with Docker Compose

Install Docker first if needed (guide). Then:

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

compose.yaml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"
docker compose up -d

Check the project’s README for the current major version tag; version 2 introduced changes such as optional MariaDB storage.

2. Put it behind HTTPS

/etc/nginx/sites-available/status:

server {
    listen 80;
    server_name status.example.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;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Uptime Kuma’s interface uses WebSockets, so the Upgrade/Connection headers are required.

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

Open https://status.example.com and create the admin account immediately — until you do, anyone who reaches the page can.

3. Add monitors

Click Add New Monitor and pick a type:

Type Use it for
HTTP(s) Websites and APIs; checks status code, optional response time
HTTP(s) – Keyword Page must contain (or not contain) a word — catches “200 OK but broken” pages
HTTP(s) – JSON Query API returns an expected value
TCP Port SSH, database, mail and game servers
Ping Host reachability
DNS A record resolves to the expected IP
Docker Container Container is running (mount the Docker socket — read-only isn’t enough, so weigh the risk)
Push The monitored job calls Uptime Kuma; alert if it stops (cron jobs, backups)

Sensible settings for a website: interval 60 seconds, retries 2–3 before alerting (avoids alerts on a single blip), and Certificate Expiry Notification enabled — it warns you days before an HTTPS certificate expires.

Push monitors for cron jobs

Create a Push monitor, copy its URL, and call it at the end of a job:

30 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 "https://status.example.com/api/push/AbCdEf?status=up&msg=OK" > /dev/null

If the backup fails or doesn’t run, no push arrives and you get an alert. See the crontab guide.

4. Notifications

Settings → Notifications supports Telegram, Discord, Slack, Microsoft Teams, email (SMTP), ntfy, Gotify, Pushover, webhooks and many more. Set one up as default so new monitors use it automatically.

Telegram in short: create a bot with @BotFather, get its token, send the bot a message, then let Uptime Kuma auto-detect your chat ID.

5. Status pages

Status Pages → New Status Page creates a public page listing selected monitors, with uptime history and incident messages. Point a subdomain at it — customers check status.example.com instead of emailing you during an outage.

6. Maintenance windows

Schedule maintenance so planned downtime doesn’t trigger alerts or hurt your uptime percentage.

Backups and updates

Everything lives in ./data (an SQLite database by default). Back it up with the rest of the server:

docker compose stop
tar czf ~/uptime-kuma-$(date +%F).tar.gz -C ~/uptime-kuma data
docker compose start

Update:

docker compose pull && docker compose up -d

Security tips

  • Enable 2FA in Settings → Security.
  • Don’t expose port 3001 directly; keep the 127.0.0.1 binding.
  • If you add Docker monitors, understand that access to the Docker socket is root-equivalent.

Uptime Kuma vs a full monitoring stack

Uptime Kuma answers “is it up?” from the outside. For CPU, memory, disk and application metrics from the inside, pair it with Netdata or Prometheus and Grafana, and see CPU and RAM monitoring.

A monitoring server should be reliable and independent. A small VPS in a different location from your main servers — for example a Tokyo monitor for USA servers — gives you a true outside view.

  • Monitoring
  • Uptime Kuma
  • Self-Hosting