How to Monitor Your Server with Uptime Kuma (Get Told When Something's Down)
A home server fails quietly. Nextcloud stops syncing, the website 502s, the backup drive unmounts, and you find out a week later. Uptime Kuma checks everything you point it at every minute and sends a message to your phone the moment something stops answering — and another when it's back.
Quick reference
| Task | What |
|---|---|
| Install | Compose file below, then http://server-ip:3001 |
| Check a website | Add New Monitor → HTTP(s) |
| Check a Docker app | HTTP(s) to its port, or Docker Container |
| Check a device is on | Ping |
| Check a port (SSH, Samba) | TCP Port |
| Alerts | Settings → Notifications (Telegram, email, Discord, 90+ others) |
1. Install
mkdir -p ~/docker/uptime-kuma && cd ~/docker/uptime-kuma
nano compose.yaml
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
ports:
- "3001:3001"
volumes:
- ./data:/app/data
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
The docker.sock line is optional; it lets Kuma check containers directly.
docker compose up -d
Open http://192.168.1.50:3001 and create your admin login.
2. Add monitors
Click Add New Monitor. The useful types:
- HTTP(s) — your website, Nextcloud, Pi-hole's admin page. It's up if the page returns 200. Use HTTP(s) – Keyword to also check the page contains a word, which catches "the server answered but with an error page".
- TCP Port — SSH (22), Samba (445), MariaDB (3306). Up if the port accepts a connection.
- Ping — your router, printer, NAS, the Pi in the shed.
- Docker Container — up if the container is running.
- DNS — ask Pi-hole to resolve a name; proves DNS is working.
Set the interval to 60 seconds and Retries to 2 so a single blip doesn't page you.
3. Get alerts on your phone
Settings → Notifications → Setup Notification. The two easiest:
- Telegram: message @BotFather on Telegram, /newbot, copy the token; message your new bot once; paste the token in Kuma and click Auto Get for the chat ID.
- Email (SMTP): your email provider's SMTP details, or a Gmail app password.
Tick Default enabled and Apply on all existing monitors. Send a test.
4. Watch certificates
In an HTTP monitor, under Advanced, tick Certificate Expiry Notification. You'll be warned at 21, 14 and 7 days — handy if Certbot's renewal ever silently fails.
5. A status page
Status Pages → New gives you a public page listing what's up. Share it with the family so "is the server down?" becomes a link rather than a message to you.
Put it behind the proxy
Add a server block for status.example.com pointing at 127.0.0.1:3001 (tutorial 28) — it needs the WebSocket lines — and change the ports line to "127.0.0.1:3001:3001".
Troubleshooting
Everything shows down from Kuma but works in a browser. Kuma runs inside Docker and can't use localhost to mean the server. Use the server's LAN IP, or the container name if they share a Docker network.
Telegram test fails. You haven't messaged the bot first — bots can't start conversations.
"Monitoring itself" shows down when the server reboots. Expected; you can't monitor the monitor. For that, use a free external service (UptimeRobot, Healthchecks.io) to ping your status page.
Alerts flap on and off. Raise Retries or the interval; a Wi-Fi device like a phone will come and go.
Wrapping up
One container, one monitor per thing you care about, one notification channel to your phone. Add the certificate check and a status page, and you'll hear about every outage first — usually before anyone else has noticed.
