Install Uptime Kuma for self-hosted monitoring
Uptime Kuma is the self-hosted "is my service up?" dashboard: HTTP, TCP, ICMP, Docker container checks, with alerts to Telegram, Slack, Discord, email, and 80+ other targets. Five minutes from docker compose up to "the first time a service goes down I get a message."
Why host monitoring on a different VPS
The most common Uptime Kuma mistake: install it on the same box as the things it monitors. When the box goes down, your monitor goes down with it — you only find out from users. Run Uptime Kuma on a different VPS, ideally in a different provider or region.
For a self-hoster, this is the one case where "spend $4 on a second VPS just for monitoring" is genuinely worthwhile.
The Compose file
mkdir -p ~/uptime-kuma && cd ~/uptime-kuma
nano docker-compose.yml
name: uptime-kuma
services:
uptime-kuma:
image: louislam/uptime-kuma:1
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- uptime_kuma_data:/app/data
deploy:
resources:
limits:
memory: 512M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
volumes:
uptime_kuma_data:
louislam/uptime-kuma:1 floats within v1 — patch updates land automatically. For pinned behavior swap to a specific tag.
Bring it up + Nginx
docker compose up -d
docker compose logs -f uptime-kuma
Then put Nginx + HTTPS in front, same as our pattern:
sudo nano /etc/nginx/sites-available/status
server {
listen 80;
server_name status.example.com;
location /.well-known/acme-challenge/ { root /var/www/html; }
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
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 --redirect
First-user setup
Visit https://status.example.com/. First load asks you to create the admin account. Pick a strong password. Lock down with an IP allowlist in Nginx if Uptime Kuma is for your own use only:
location / {
allow YOUR.HOME.IP;
deny all;
# ... proxy_pass ...
}
Adding monitors
Click "+ Add New Monitor." Useful monitor types:
- HTTP(s) — your web apps, n8n editor, Open WebUI. Check status code and optionally a response keyword.
- Push — give the monitor a URL; your script pings that URL on a schedule. Perfect for "is my cron job running?" health.
- Keyword — HTTP plus a body match. "Does the response contain 'OK'?"
- Ping — ICMP reachability. Useful for routers, IoT devices, VPN endpoints.
- Docker Container — checks a container's healthcheck on a remote Docker host (mount the socket carefully).
- JSON Query — HTTP + JSONPath against the response body. "Is
data.queue_length < 100?"
For a typical self-hosted stack, you want one monitor per public URL plus a Push monitor for any background job.
Notifications that actually wake you up
Settings → Notifications → Setup Notification. Telegram is the fastest path to a phone alert:
- Create a bot via @BotFather, get the token.
- Message your bot once (so it can DM you back).
- Get your chat ID from
https://api.telegram.org/bot<TOKEN>/getUpdates. - Paste both into Uptime Kuma's Telegram notification config.
For more critical alerts, also set up an email or Pushover notification — Telegram is fast but can be missed.
Status page (optional)
Uptime Kuma can publish a public status page at https://status.example.com/status/main. Good for letting users see "yes, the outage you're experiencing is real, we're aware." Configure who sees which monitors per page.
Heartbeat / Push monitors for cron jobs
For background work (backups, scheduled scripts), use Push monitors. Uptime Kuma gives you a unique URL per monitor; your script curls it on success:
# In your backup script
# At the end, after success:
curl -fsS -m 10 --retry 3 https://status.example.com/api/push/abc123?status=up > /dev/null
If the URL isn't hit within the heartbeat interval, the monitor goes red and you get alerted. Two lines added to a script give you "did my Sunday backup actually run?" peace of mind.
Backing up Uptime Kuma
All state lives in the uptime_kuma_data volume. Back up the same way as our n8n pattern. Restoring after a host failure is the difference between 5 minutes of reconfiguration and a weekend of "what monitors did I have?"
Common Uptime Kuma mistakes
"All monitors went red at the same time"
The Uptime Kuma host's outbound network is down, not your monitored services. Set up a second Uptime Kuma on a different provider and have each watch the other.
"Notifications spam at every check"
Default notification config repeats every interval. Set "Retry every X minutes" higher, and use "Resend Notification if Down X times consecutively" to throttle.
"HTTPS monitor green but the site is broken"
HTTP 200 doesn't mean the app works. Add a Keyword monitor checking for a string that only appears when the page is genuinely rendered (e.g., a button label).
"Push monitor goes red even though the cron job ran"
Outbound from the cron host failed (firewall, DNS, transient timeout). Add --retry 3 --max-time 10 to the curl call; ignore transient cron failures.
VPS specifically for monitoring?
Uptime Kuma uses ~150 MB RAM. A $3.49 Inferno plan in a different location than your main box is perfect — and gives you the "different network" property that makes monitoring trustworthy.
What to do next
- Back up Uptime Kuma's data volume.
- Harden the monitoring host — it's a single-purpose box, lock it down.
- Docker hardening.
Author: Daniel Ferro — Lisbon. Last tested: 2026-05-22 on Uptime Kuma 1.23.x, Docker CE 27.3.