Installer Uptime Kuma
Surveillez vos services homelab et recevez des alertes en cas de panne.
What you'll build
Uptime Kuma is a self-hosted uptime monitor with a beautiful UI. It repeatedly checks your services and notifies you the instant one becomes unreachable, so you find out before your family does. It can also publish clean status pages, track SSL certificate expiry and watch scheduled jobs such as backups.
Plan for 15 minutes on a host with Docker installed. For the bigger picture of what to monitor and why, see the monitoring guide.
Step 1: Deploy with Docker
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
restart: unless-stopped
ports:
- "3001:3001"
volumes:
- ./data:/app/data
# Optional, for Docker container monitors (read-only):
# - /var/run/docker.sock:/var/run/docker.sock:rodocker compose up -dOpen http://your-server-ip:3001 and create your admin account with a strong password. All settings and history are stored in ./data, so include it in your backups. The :1 tag follows the stable version 1 line; newer major versions exist, so read the release notes and back up before you change the tag.
Mounting the Docker socket gives the container visibility of other containers, but it also gives it significant power over Docker. Do it read-only, and only if you need Docker monitors.
Step 2: Add your first monitors
Click Add New Monitor. The monitor type determines what "up" means:
- HTTP(s) — checks a URL returns a good status code. Best for web apps and dashboards.
- HTTP(s) – Keyword — also checks the page contains (or lacks) certain text, which catches pages that load but show an error.
- TCP Port — checks a port accepts connections. Good for databases and non-HTTP services.
- Ping — checks a host responds to ICMP. Good for routers, NAS, switches.
- DNS — checks a record resolves. Good for verifying Pi-hole or AdGuard.
- Docker Container — checks a container is running (needs the Docker socket).
- Push — the service calls Uptime Kuma, instead of the other way around. Ideal for backup jobs.
Set a friendly name, the target, and a check interval (60 seconds is a sensible default).
Step 3: Configure notifications
This is the whole point — set it up before you need it. Go to Settings → Notifications → Setup Notification and pick a channel:
- Telegram or Discord — great for instant phone pushes.
- ntfy or Gotify — self-hosted, privacy-friendly push notifications.
- Email (SMTP) — universal fallback.
Attach the notification to each monitor (or set it as default for new ones). Send a test to confirm it actually reaches your phone. Consider two channels for critical services, so one failing notification path doesn't hide an outage.
Step 4: Monitor your backups with a push monitor
A backup that silently stops is worse than no backup, because you believe you are protected. Create a Push monitor with an expected interval (for example 25 hours for a daily backup). Uptime Kuma gives you a URL. At the end of your backup script, call it only on success:
#!/bin/bash
set -e
restic backup /srv/data
curl -fsS "https://kuma.example.com/api/push/TOKEN?status=up&msg=OK"If the URL is not called within the interval, you get an alert. The same technique works for scrubs, certificate renewals and any scheduled job. See the backup strategy guide.
Step 5: Group and organise
As you add services, use monitor groups and tags to organise them (for example "Media", "Network", "Backups"). This keeps a busy dashboard readable and lets you reason about which subsystem is affected during an incident.
Step 6: Watch certificates and DNS
Enable certificate expiry notifications for HTTPS monitors so you are warned weeks before a certificate lapses. Add a DNS monitor for your most important hostnames, and a ping or HTTP monitor for an external site, so you can tell the difference between "my internet is down" and "my server is down".
Step 7: Publish a status page
Under Status Pages, create a page and add the monitors you want visible. You can:
- Add your logo and a custom domain.
- Show incident history and uptime percentages.
- Post maintenance announcements, and schedule maintenance windows so planned downtime does not trigger alerts.
- Share the link with your household so they can self-check before messaging you.
Step 8: Tune to avoid alert fatigue
Good monitoring is quiet monitoring. To avoid false alarms:
- Add retries (for example 2–3) so a single blip doesn't page you.
- Use a slightly longer interval or timeout for services that are naturally slow to respond.
- Don't monitor everything; monitor what you would act on.
- Review alerts monthly and remove noisy ones.
Run Uptime Kuma safely
- Put it behind a reverse proxy with HTTPS if you want remote access, and enable WebSocket support, which the UI needs.
- Prefer a VPN over exposing it.
- Run it on a different machine from the thing it monitors if you can; if the monitoring host dies, it can't tell you. A small second instance on a spare device that watches the first is a cheap safeguard.
Where Uptime Kuma fits
Uptime Kuma answers "is it up?" extremely well. For "how is it performing over time" (CPU, RAM, disk, temperature), pair it with Grafana and Prometheus. Together they cover the full monitoring picture.
Troubleshooting
- False downs on HTTPS — accept self-signed certificates in the monitor settings, or monitor the internal HTTP port.
- Docker monitors fail — ensure the Docker socket is mounted and readable.
- No notifications — re-test the channel; many require a bot token or webhook URL.
- Everything shows down after a reboot — the monitor host may start before the network is ready; add retries.
- UI won't load behind a proxy — WebSockets are not forwarded; enable them.
Next steps
Add a monitor for your internet connection (ping a reliable external host), for each critical service, and for your backups (a push monitor your script calls on success), so a silent backup failure becomes a visible alert.
Articles connexes
How to Set Up Grafana and Prometheus
Stand up a metrics stack with Prometheus, node_exporter, cAdvisor and Grafana to visualize your home server's health, with retention, security and alerting tips.
Installer Home Assistant
Exécutez Home Assistant Container sur votre serveur pour une domotique locale.
Home Server Monitoring: A Complete Guide
Monitor your homelab with Uptime Kuma, Prometheus and Grafana: what to track, sensible alert thresholds, SMART disk health, backup checks and how to avoid alert fatigue.