How to Run Uptime Kuma: Status Page and Uptime Monitor

Uptime Kuma has become one of the most popular self-hosted monitoring tools because it solves a very practical problem without demanding a full observability stack. If you want to know whether your website, API, VPN endpoint, or internal dashboard is up, Uptime Kuma gives you a simple interface, useful notifications, and an optional status page that is easy to share.

That combination explains its popularity. Many self-hosters do not need enterprise monitoring on day one. They need a reliable way to check whether core services respond, detect obvious outages, and communicate service health to teammates or users. Uptime Kuma fits that need unusually well.

At a high level, Uptime Kuma lets you create monitors for HTTP, TCP, ping, DNS, keyword matching, SSL certificate expiry, and other common checks. Instead of building scripts manually, you define monitors through the web UI and review the results in a central dashboard. For small infrastructures, that is often enough to catch the most important failures early.

Quick start with Docker Compose

Uptime Kuma is a single container with a single data directory, which makes deployment about as easy as self-hosting gets. Create a directory for it and drop in this docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./uptime-kuma-data:/app/data

Then bring it up:

docker compose up -d

Open http://your-server:3001 in a browser. On first run, Uptime Kuma asks you to create the admin account — there is no default password to hunt for. Once you are in, everything else happens in the web UI.

A few things worth knowing before you go further:

• Image tags. The 1 tag tracks the long-running 1.x series, which is what most of the documentation and community guides assume. There is also a newer 2.x series with a reworked interface and support for an external MariaDB database instead of the embedded one. Check the project's releases page and pick whichever line is currently marked stable; the compose file above works for either — just change the tag.
• Where your data lives. Everything — monitors, history, notification settings, status pages — sits in /app/data, backed by an embedded database. Back up that one directory and you can rebuild the whole install. If you follow the 3-2-1 backup approach we recommend for self-hosted services, this folder belongs in it.
• Prefer a bind mount or named volume, never neither. If you skip the volume, an image update wipes your monitor history and configuration.

For a broader look at writing compose files that survive updates and reboots, see our guide to Docker Compose best practices for production.

Creating your first monitor

Click Add New Monitor, pick HTTP(s), and enter the URL you care about. The defaults are sensible: a heartbeat interval of 60 seconds and a few retries before a service is marked down. Give the monitor a friendly name — it is what will appear on your status page later — and save. Repeat for a TCP port, a ping target, or a keyword check as needed.

Publishing a status page

Status pages are built in, not an add-on. Go to Status Pages, click New Status Page, and give it a name and a slug. Then add the monitors you want to expose, grouped however makes sense (for example "Websites" and "APIs"), and hit Save. The page is immediately live at http://your-server:3001/status/your-slug. You can toggle whether it is public, add an incident banner during outages, and attach a custom domain if you put a reverse proxy in front.

The gotcha: WebSockets behind a reverse proxy

The most common first-day problem is putting Uptime Kuma behind a reverse proxy and getting a dashboard that loads but never connects. The UI communicates over WebSockets, so your proxy must pass upgrade headers through. Caddy and Traefik handle this automatically. For Nginx you need something like:

location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

If the dashboard shows a connection error behind a proxy, this is almost always why.

Deciding what to monitor

A sensible Uptime Kuma setup usually includes:

• monitors for your public sites and APIs
• checks for reverse proxies, authentication portals, and critical internal tools
• notification routing to email, chat, or incident tools
• one or more status pages for the services people actually care about

The most important design decision is not the tool itself. It is what you choose to monitor. A homepage returning HTTP 200 is useful, but it may miss deeper problems. If your login flow can fail while the homepage still loads, monitor the login endpoint or a protected application path. If a certificate expiration would break access, enable SSL monitoring. If a specific phrase on the page indicates normal app health, a keyword monitor may be more meaningful than a simple response code. Our self-hosted server monitoring checklist walks through this decision layer by layer.

Placement matters too. If Uptime Kuma lives on the same host as every monitored service, it may disappear during the same outage. For homelabs and small VPS environments, that is common and not always avoidable. But for your most important public services, it is better if at least some checks run from a different machine or network. Monitoring is most valuable when it survives the failure.

Tuning alerts so you keep trusting them

Alerting should be tuned carefully. One of the fastest ways to ruin a monitoring setup is to make it noisy. Tiny timeouts and hyper-frequent checks can produce false alarms, especially on slower services or modest home connections. It is usually better to alert after a short confirmation window than to blast notifications for every transient hiccup. We cover this trade-off in more depth in our guide to alerting for self-hosted services.

The status page deserves the same discipline. Only expose the services that are meaningful to your intended audience. If the page is public, avoid leaking unnecessary internal system names or architecture details. A clean status page should answer a simple question: which services are healthy, degraded, or down? It should not become a map of your whole infrastructure.

Grow the setup gradually

Uptime Kuma is also a great fit for incremental monitoring. Start small. Add your public website, a key API, your reverse proxy, and your authentication service. Once you trust the alerts, expand to internal dependencies and certificate checks. This gradual approach works better than creating thirty monitors on day one and then ignoring them because the dashboard turned into wallpaper.

Another advantage is maintenance simplicity. Uptime Kuma is widely deployed in Docker-based self-hosting setups, and its interface is easy to revisit after time away. That matters more than people admit. A monitoring tool only helps if you still understand it three months later during a real incident.

Where Uptime Kuma fits

My recommendation is to use Uptime Kuma as the front door of a practical monitoring strategy. Let it detect reachability problems, certificate issues, and obvious application failures. Use the status page to communicate clearly. Then pair it with logs and metrics for deeper troubleshooting. On its own, Uptime Kuma will not explain every outage, but it is one of the best lightweight tools for making sure you know an outage happened in the first place.

If you run a small self-hosted stack, that is usually the right level of ambition. Good monitoring does not have to start complicated. It has to start reliable. Uptime Kuma earns its place by being easy to deploy, understandable to maintain, and useful before your infrastructure becomes large enough to justify something heavier.

The example binds the application port to 127.0.0.1 on the host. For initial setup on a remote host, use an SSH tunnel or a private management connection; a public-server URL will not reach that loopback binding directly. Configure the authenticated HTTPS reverse proxy before making the service public.