Monitor Everything You Host, Without Trusting Anyone Else to Do It
If you run self-hosted services, you already know the anxiety of not knowing when something breaks. Uptime Kuma is an open-source monitoring tool that gives you a live status dashboard, alert notifications, and a public-facing status page – all running on your own infrastructure. No subscription, no third-party data collection, no monthly cap on the number of monitors you can create.
Getting it running takes under an hour even for first-timers. The setup involves Docker, a few configuration choices, and optional reverse proxy configuration if you want it accessible from outside your local network. This guide walks through the full process from installation to a working status page.
What You Need Before You Start
Uptime Kuma runs as a Docker container, so the baseline requirement is a Linux server or VPS with Docker and Docker Compose installed. A Raspberry Pi 4, a home server, or any cloud VPS with at least 512MB of RAM will handle it without issues. The application itself is lightweight – it doesn’t need a separate database since it uses SQLite internally, which simplifies the setup considerably.
You will also want a domain name if you plan to expose the status page publicly. This is optional for internal-only monitoring, but a public status page is one of Uptime Kuma’s most useful features for anyone running services that other people depend on. If you already manage containers through a UI, you may have Portainer set up as a Docker management interface, which can make deploying and restarting the Kuma container more convenient.
For notifications, Uptime Kuma supports a wide range of alert channels out of the box – email via SMTP, Telegram, Discord, Slack, Gotify, ntfy, and many others. Have your credentials for at least one notification channel ready before you start. Setting up alerts during initial configuration is much easier than going back to it afterward.
Installing Uptime Kuma with Docker Compose
Create a directory for the project and a docker-compose.yml file inside it. The configuration is minimal. You need the louislam/uptime-kuma:1 image, a volume mount for persistent data, and port mapping – typically 3001:3001. Set the restart policy to unless-stopped so the container comes back automatically after a reboot. The full compose file looks like this:
version: '3.8'
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
volumes:
- ./data:/app/data
ports:
- 3001:3001
restart: unless-stopped
Run docker compose up -d from that directory and the container will pull and start within a minute. Navigate to http://your-server-ip:3001 in a browser and you will land on the initial setup screen, which prompts you to create an admin username and password. Do not skip a strong password here – if you later expose this to the internet, the login page is the only thing standing between your monitor configuration and anyone who finds the URL.
Configuring Monitors and Building Your Status Page
Once logged in, the dashboard is clean and self-explanatory. Click “Add New Monitor” to create your first check. Uptime Kuma supports HTTP/HTTPS, TCP port, DNS, Ping, Docker container health, and several other monitor types. For web services, the HTTP(S) type is the most useful – it checks that a URL returns a successful response code and can optionally verify that specific keyword appears in the response body, which protects against cases where a server returns 200 but the application itself has crashed.
Set the heartbeat interval based on how quickly you need to know about outages. The default is 60 seconds, which is reasonable for most self-hosted setups. Dropping it to 30 seconds doubles the check frequency without creating meaningful server load. Set the retry count to at least 2 or 3 before an alert fires – single-packet failures happen and will generate false alarms if retries are disabled. Each monitor can have its own notification channel, so a critical service like a VPN or home automation hub can alert via phone notification while a lower-priority service just logs to a Discord channel.
The status page feature is separate from the monitoring dashboard and is what external users or team members see. Go to “Status Page” in the sidebar, click “New Status Page,” and give it a slug – this becomes the URL path. From there you can add a page title, description, custom logo, and choose which monitors appear on the page. Monitors can be grouped into sections, which is useful when you are tracking separate categories like “Media Services,” “Network Infrastructure,” and “Home Automation.” The layout is responsive and loads fast even on mobile, which matters when someone is checking whether your service is down from their phone.
Custom domains for the status page require a reverse proxy in front of Uptime Kuma. Nginx Proxy Manager and Caddy are both popular choices. Point your proxy at port 3001 on the Kuma container, configure your SSL certificate, and the status page will serve at your chosen domain. One practical consideration: host the status page on a different server or subdomain from the services it monitors. If your main server goes down and takes Kuma with it, the status page showing an outage will also be unreachable – which defeats the purpose.
Notification setup lives under Settings > Notifications. Each notification type has its own form – for Telegram you need a bot token and chat ID, for Discord a webhook URL, for SMTP you provide the usual mail server credentials. After saving a notification provider, use the “Test” button before assigning it to any monitors. Notification delivery failures are silent by default, so a misconfigured SMTP server will simply never send alerts until you check the logs and notice.
One underused feature is the maintenance scheduling system. Under Settings > Maintenance, you can create scheduled windows during which monitors are paused and the status page shows a planned maintenance banner rather than a red “down” indicator. For anyone running updates or reboots on a schedule, this prevents a flood of alerts and keeps the status page accurate without manual intervention. It supports recurring schedules, not just one-time windows, so a weekly maintenance window can be configured once and left alone.
Uptime Kuma stores all data in a single SQLite file at /app/data/kuma.db inside the container, mapped to your local volume. Back that file up regularly – losing it means losing every monitor configuration, status history, and notification setup. A simple cron job that copies the file to a remote location daily is enough protection for most use cases. The application does not currently offer built-in backup scheduling, so this is entirely a manual responsibility.
