Set Up Uptime Kuma for Self-Hosted Service Status Monitoring

Why Self-Hosters Need a Status Monitor

Running your own services means owning every failure. When Jellyfin goes down at midnight or your home VPN stops responding, nobody sends you an alert – unless you’ve built that system yourself. Uptime Kuma is a self-hosted monitoring dashboard that watches your services around the clock and notifies you the moment something breaks.

What Uptime Kuma Actually Does

Uptime Kuma is an open-source monitoring tool built with Node.js and Vue.js, designed to run entirely on your own hardware without sending data to any third-party cloud. It polls your services at set intervals, logs response times, calculates uptime percentages, and pushes notifications through dozens of channels including Telegram, Discord, Slack, email, and Gotify. The interface runs in a browser and gives you a live dashboard of every monitor you’ve configured.

The tool supports several monitor types beyond simple HTTP checks. You can monitor TCP ports, DNS records, Docker containers, database connections via keywords in a page response, and even SSL certificate expiry dates. That flexibility matters for a home lab setup where you might be running a mix of web apps, game servers, and internal network services on different protocols.

Notification options are where Uptime Kuma earns its reputation. Most self-hosted alternatives in this space require manual configuration of notification scripts or third-party services bolted on as an afterthought. Uptime Kuma ships with over 90 notification integrations built directly into the UI, meaning you configure everything through a form rather than a config file. For most home lab operators, that’s the difference between actually setting up alerts and putting it off indefinitely.

One feature that tends to surprise new users is the status page builder. Beyond internal monitoring, Uptime Kuma lets you publish a public-facing status page for your services – the kind of page that professional SaaS companies use to communicate outages. If you share services with friends or family, that public page gives them somewhere to check before they message you asking why Jellyfin isn’t loading.

Installing and Configuring Uptime Kuma Step by Step

Docker is the fastest path to a working installation. If you already have Docker and Docker Compose on your host machine, create a new directory for the project, then drop in a docker-compose.yml file. The service definition is minimal – you only need to specify the image, set the restart policy to unless-stopped, map port 3001 on the host to port 3001 in the container, and mount a local volume to /app/data so your configuration persists across container restarts. Run docker compose up -d and the container pulls and starts in under a minute.

Open a browser and navigate to http://your-server-ip:3001. On first load, Uptime Kuma prompts you to create an admin username and password – do not skip setting a strong password here, especially if this port is accessible outside your local network. Once logged in, you land on the main dashboard, which is empty until you add your first monitor.

Click Add New Monitor in the top right. For a basic web service, select HTTP(s) as the monitor type, give it a friendly name, and paste in the URL of the service you want to watch. The heartbeat interval defaults to 60 seconds, which is reasonable for most home lab services – dropping it below 20 seconds on a machine with many monitors can increase CPU load noticeably. Set the number of retries before marking a service as down to at least 2 or 3, which prevents a single slow response from triggering a false-positive alert. Save the monitor and Uptime Kuma immediately begins polling.

Notifications require their own setup step. Navigate to Settings > Notifications and add at least one notification method. Telegram is a popular choice because setup takes about two minutes: create a bot via BotFather, copy the token, find your chat ID, paste both into Uptime Kuma’s Telegram fields, and test the connection with the built-in test button. Once saved, go back to each monitor, edit it, and assign the notification channel – monitors don’t inherit a default notification source automatically, so this step is easy to miss on a first setup.

If you’re running Uptime Kuma behind a reverse proxy – which you should be if you plan to access it remotely over HTTPS – the configuration requires one specific setting. Uptime Kuma needs WebSocket support enabled on the proxy level to function correctly. If you’re using Caddy, the setup is straightforward: a simple reverse_proxy directive with your server’s local address handles it without additional headers. For Nginx, you’ll need to explicitly pass the Upgrade and Connection headers in the proxy configuration block. Skipping this step results in the dashboard loading but failing to update live status. You can find the full reverse proxy walkthrough in the guide to setting up Caddy as a reverse proxy for self-hosted services.

Building Status Pages and Managing Alerts

Status pages live under the Status Page tab in the sidebar. Create a new page, assign it a slug that becomes part of the URL path, and then drag monitors into groups on the page. You can make the page public without any authentication, or keep it private behind Uptime Kuma’s own login. The design is clean and minimal by default, with options to add a custom logo, a description header, and links to your own incident update channels. Each monitor on the page shows its current status, a 90-day uptime bar, and average response time – enough detail to be genuinely informative without being overwhelming.

Alert fatigue is a real problem once you have more than a dozen monitors running. A service that frequently sits on the edge of its response time threshold will generate constant noise if your retry count is too low or your heartbeat interval too aggressive. The fix is straightforward: raise the retry count to 3 or 4, set a minimum 60-second interval for non-critical services, and use Uptime Kuma’s maintenance feature to silence specific monitors during planned downtime windows rather than deleting and recreating them. Getting that configuration right the first time saves considerable notification noise later.