If you’re running a homelab, you need to know when things break. Uptime Kuma is a self-hosted monitoring tool that watches your services and alerts you when they go down. Installing Uptime Kuma on Docker takes about ten minutes and gives you a monitoring dashboard that actually works without vendor lock-in.
Why Self-Host Your Monitoring
Third-party monitoring services charge per endpoint. Uptime Kuma runs on your own hardware, monitors as many services as you want, and costs nothing after the initial setup. You get alerts, status pages, and historical data without touching a credit card every month.
The other reason: you control your data. No cloud vendor scraping your uptime logs. No dashboard hosted on someone else’s infrastructure. You know where your monitoring lives.
Prerequisites and Hardware
You need Docker and Docker Compose installed on a Linux box. Ubuntu Server 22.04 LTS works fine. Minimum specs: 512MB RAM and a 1GHz CPU. Kuma runs light—I’ve had it stable on a five-year-old Intel NUC using less than 100MB memory.
Network requirements: Kuma needs outbound access to any services you’re monitoring. If you’re behind a firewall or proxy, you’ll need to configure that later. Allocate a static IP or DHCP reservation for your monitoring box.
One more thing: pick a subdomain or port you’ll use to reach Kuma’s dashboard. The default is port 3001. If that conflicts with something else on your network, you’ll change it in the compose file.
Step 1: Create the Docker Compose Configuration
Create a directory for Kuma and a docker-compose file inside it.
mkdir ~/uptime-kuma
cd ~/uptime-kuma
nano docker-compose.ymlPaste this configuration:
version: '3.8'
services:
uptime-kuma:
image: louislam/uptime-kuma:latest
container_name: uptime-kuma
restart: always
ports:
- "3001:3001"
volumes:
- ./data:/app/data
environment:
- TZ=UTC
networks:
- kuma-network
networks:
kuma-network:
driver: bridgeThat TZ variable is important. Set it to your actual timezone (America/New_York, Europe/London, etc.) so alert timestamps make sense. The volume mount keeps your data persistent if the container restarts. The network is there because later you might add reverse proxy or notification containers.
If port 3001 is taken on your system, change the first 3001 to something else (e.g., 8080:3001). The second one stays 3001—that’s the internal container port.
Step 2: Start Kuma and First-Run Setup
Launch the container:
docker-compose up -dCheck if it’s running:
docker-compose psYou should see uptime-kuma with status “Up”. If it says “Exited”, run docker-compose logs to see the error. Usually it’s a port conflict or a permission problem on the data directory.
Open your browser and navigate to http://your-server-ip:3001. You’ll hit the setup screen. Create an admin account. Use a strong password—this is your monitoring nerve center. After login, you’re in.
Step 3: Configure Your First Monitors
Click the plus button to add a new monitor. Uptime Kuma supports HTTP, TCP, DNS, ICMP ping, Docker containers, and more. Start with something simple: your router’s web interface, your NAS, or a public service you depend on.
The gear I run for this
Hardware from my own homelab, relevant to this guide — direct Amazon links.
Affiliate links — I earn a small commission at no extra cost to you. Browse my full homelab store →
For an HTTP monitor, fill in:
- Name: Something descriptive (e.g., “Home Server”)
- URL: The full HTTP or HTTPS address
- Interval: How often to check (default 60 seconds is fine)
- Retries: How many failed checks before alerting (I use 2)
Save it. Kuma will immediately test the endpoint and show green or red. This is the actual value of the tool—in one glance, you see what’s alive.
For TCP monitors (useful for SSH, databases, game servers), pick TCP and enter the IP:port. Kuma attempts a connection. If it succeeds, the service is up. No HTTP overhead needed.
Common Gotchas and Fixes
Firewall blocking checks: If Kuma can’t reach a service, check your firewall rules. If monitoring an external service, that service’s firewall might be blocking your homelab IP. You may need to whitelist it.
SSL certificate errors: By default, Kuma validates HTTPS certificates. If you’re monitoring a service with a self-signed cert, the check will fail. Go to the monitor settings and disable “Ignore TLS Error” temporarily to verify it’s a cert issue, then decide whether to skip validation. This is a security trade-off—you’re accepting unverified certificates, which is fine for internal stuff, risky for anything else.
Kuma says everything is down on first start: Wait 30 seconds. It’s slow to initialize. If things stay red, check that your server can actually reach the monitored services. Run a manual ping or curl from the command line to confirm connectivity.
Memory leaks after a few days: This happened to me once. It was related to checking too many endpoints too frequently. If you’re monitoring 50+ services with 10-second intervals, dial back the frequency. Check the logs: docker-compose logs uptime-kuma. Look for repeating error patterns.
The data directory fills up: Uptime Kuma stores historical data indefinitely. After a year of monitoring, the SQLite database can hit 1-2GB. You can prune old records in the settings under Data. Set a retention policy (e.g., keep 180 days of history).
Adding Notifications and Alerts
Monitoring is useless if you don’t know when something breaks. Kuma supports Slack, Discord, Telegram, email, webhooks, and twenty other notification channels.
Go to Settings → Notifications → Add Notification. Pick your service. For Discord, paste a webhook URL from your server. For Telegram, use a bot token and chat ID. For email, configure SMTP settings.
After saving the notification, test it. You should get a message immediately. Then attach the notification to your monitors: open a monitor, scroll to “Notification”, and assign the notification channel.
Create a status page if you want something public. Under Status Page, add monitors you want to display. Generate a public link. Share it with family or colleagues so they can see your uptime without accessing Kuma’s full dashboard. This is handy if you host services for others.
Next Steps: Integrations and Scaling
Uptime Kuma monitors availability. It doesn’t analyze why something failed or predict problems. That’s where tools like n8n or Node-RED come in. You can webhook Kuma alerts into n8n, parse the error, check recent logs, and feed analysis back to Discord or email. This reduces alert fatigue because you get context, not just “service down” notifications.
If you’re running multiple services that depend on each other, set up monitor groups in Kuma’s UI so you can see dependency chains at a glance. Docker container monitors are especially useful—you can watch if a specific container restarts repeatedly, which often signals a configuration problem or resource exhaustion.
After your first week running Kuma, you’ll notice which of your services are actually fragile. That’s the real insight. The tool is honest about your infrastructure. Use that to fix what matters most.
FAQ
Can Uptime Kuma run on a Raspberry Pi?
Yes. A Pi 4 with 2GB RAM is more than enough for 50+ monitors. A Pi 3 works but gets tight with many simultaneous checks. Use a fast SD card or SSD boot—slow I/O will make Kuma sluggish when querying historical data.
How much RAM does Uptime Kuma actually use?
About 60-100MB for 20-30 monitors at default intervals. Heavy use (100+ monitors, frequent checks, large data store) can push it to 300-400MB. It’s not a resource hog compared to Grafana or Prometheus.
What’s the difference between Uptime Kuma and Grafana?
Uptime Kuma is a lightweight monitoring frontend designed for availability and alerts. Grafana is a time-series dashboarding tool that typically sits on top of Prometheus or similar databases. Kuma works standalone. Grafana requires a separate backend. For simple uptime checking, Kuma is simpler; for deep metrics and trending, Grafana is more powerful.
Does Uptime Kuma work behind a reverse proxy?
Yes, but you need to configure the reverse proxy correctly. Set up a rule to forward requests to port 3001, and add a header like X-Forwarded-Proto: https if using HTTPS. Without proper headers, Kuma might not recognize HTTPS and redirect loops happen.
Can I back up my Uptime Kuma monitors and settings?
Yes. The data is stored in the ./data directory that you mounted as a volume. Backup that entire directory and you can restore Kuma on another machine. Settings, monitors, notification channels, and historical data all come back. Docker makes this seamless—just move the data folder and restart the container.
Explore Uptime Kuma in our AI Homelab Toolkit.