How to Use Uptime Kuma: The Beginner's Guide (2026)

CodexFuse Team · 2026-10-30T12:48:17.258Z · 11 min read

Uptime monitoring sounds like a luxury until your site goes down at 2 a.m. and you hear about it from an angry user the next afternoon. How to use Uptime Kuma is the question every new self-hoster asks once they realize hosted monitoring services charge a monthly fee for something a single Docker container can do for free. This Uptime Kuma for beginners guide covers the complete workflow: install it with Docker, create your admin account, add your first monitor, tune heartbeat intervals, set up notifications that actually wake you, and publish a public status page.

If you only need a one-off check and do not want to install anything, CodexFuse's free website uptime monitor tests any URL from your browser in seconds. This guide is for the always-on monitor you own and control. If containers are new to you, skim our Docker beginner guide first — Uptime Kuma deploys as exactly one container.

What is Uptime Kuma?

Uptime Kuma is a free, open-source, self-hosted uptime monitor created by Louis Lam. It checks your websites, APIs, ports, and servers on a schedule you choose and alerts you the moment something stops answering. Unlike hosted services, your monitors, history, and credentials live on your own server, so there is no subscription and no third party holding your data (Bitnesia).

It is one of the most-starred self-hosted projects on GitHub — roughly 88,000 stars by mid-2026, according to Matthew Wong's roundup. The whole application runs as a single container with a SQLite database file, a reactive web UI, and support for dozens of notification providers including Telegram, Discord, and email via SMTP, plus Apprise integration covering 78+ more platforms (Bitnesia). Public status pages are built in, so you can share live service health on a custom domain without paying for a premium tier (Matthew Wong).

What do you need before installing Uptime Kuma?

You need a Linux server with Docker and Docker Compose installed, plus a free port 3001 for the dashboard. Most beginners run it on a small VPS — our guide on what is VPS hosting explains the setup if you do not have one yet. One vCPU and 1 GB of RAM comfortably handles dozens of lightweight monitors (Bitnesia).

A domain name is optional but recommended if you want a public status page at something like status.yourdomain.com. Store Uptime Kuma's data on a local directory or a Docker volume, not on NFS: its SQLite database needs POSIX file locking to avoid corruption (Bitnesia).

How do you set up Uptime Kuma with Docker?

You set up Uptime Kuma with Docker by running a single container command, opening its web UI on port 3001, and completing the in-browser wizard. The whole install takes about two minutes (Lineserve).

1. Run the container. On your server, execute:
   

   docker run -d --restart=unless-stopped -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

   The flags: -d runs it in the background, --restart=unless-stopped brings it back after a crash or reboot without overriding a manual stop, -p 3001:3001 exposes the dashboard, and -v uptime-kuma:/app/data persists every monitor and setting in a named volume so upgrades never wipe your data (Bitnesia; Lineserve).
2. Pin the major version tag. Use louislam/uptime-kuma:2 (or 2-slim for the lightweight build without embedded MariaDB and Chromium). The latest tag is deprecated and points at legacy version 1, so never deploy with it (Bitnesia).
3. Open the dashboard. Browse to http://YOUR-SERVER-IP:3001 and allow port 3001 through your firewall if needed (Lineserve).
4. Choose a database. Version 2 shows a database screen first: pick SQLite for a simple single-file setup, or MariaDB if you want an external database (Bitnesia).
5. Create the admin account. Pick a username and a strong password, then store it somewhere safe before going further — the next section explains why this step has no undo button.

How do you create the Uptime Kuma admin account?

The first visitor to a fresh Uptime Kuma install gets the setup wizard, so create your admin account before the dashboard is reachable from the internet. Whoever opens the URL first owns the instance, which is why exposing port 3001 publicly before this step is a mistake (Edgible Guides).

Here is the trap every beginner must know before that first login: Uptime Kuma has no password reset by email and no reset button in the UI. If you lose the admin password, the only fix is a CLI reset inside the container. Write the credentials down the moment you create them (Bitnesia). For long-term use, do not leave port 3001 exposed directly — bind it to localhost (-p 127.0.0.1:3001:3001) and put a reverse proxy in front, covered below (Bitnesia).

How do you add your first Uptime Kuma monitor?

Click Add New Monitor, choose the HTTP(s) type, and point it at your site. Give it a friendly name like "Primary Website", enter the full URL, leave the heartbeat at 60 seconds, set 2–3 retries, and save. The dashboard immediately shows the monitor green with 100% uptime (Better Stack).

Prove it works the way the Better Stack guide does: stop the target service for a minute and watch the monitor flip red, then restart it and get the recovery state. Monitoring the host itself? Add a Ping monitor against the server IP. Monitoring an app on the same machine that is not in Docker? Point an HTTP monitor at http://host.docker.internal:PORT/ so the container reaches the host network (Better Stack).

Which Uptime Kuma monitor type should you pick?

Match the monitor type to the failure you actually fear. HTTP tells you the site works for visitors; Ping only tells you the machine is alive.

Monitor types per Bitnesia; certificate-expiry tracking noted by idroot's install guide. Most beginners need exactly two monitors to start: one HTTP(s) on the public URL and one Ping on the server.

How often should an Uptime Kuma heartbeat check?

Start with a 60-second heartbeat interval and 2–3 retries before a monitor is marked down. Uptime Kuma warns against intervals below 20 seconds because they can overload targets and create jitter false positives; 60 seconds with a couple of retries is the balanced default both Bitnesia and Better Stack recommend.

The math matters because every interval is a trade-off between detection speed and check volume. These are my computed figures per monitor at a steady interval:

Worst-case detection delay is roughly the interval multiplied by your retry count, so 60 seconds with 3 retries means a real outage pages you within about 3 minutes. Reserve 20-second intervals for revenue-critical endpoints only; run 5-minute checks on the long tail.

How do Uptime Kuma notifications work?

A monitor without alerts is a dashboard you will never look at. In Uptime Kuma, go to Settings > Notifications > Setup Notification, pick a channel, complete its form, click Test, and only then click Save. The Test button is not optional — it proves the channel delivers before a real outage (Bitnesia).

Telegram needs a bot token from BotFather and a chat ID, which Uptime Kuma can auto-fetch once you have messaged the bot. Discord needs a webhook URL from the channel's Integrations settings, and you can prefix alerts with role mentions like @everyone. Email via SMTP needs the mail server hostname and port — for Gmail that is smtp.gmail.com on port 587 with an app password, which requires 2-Step Verification enabled on the Google account first (Bitnesia; Better Stack).

Tick Apply on all existing monitors to attach the channel to everything at once, and Default enabled so every monitor you create later inherits it. Then break something on purpose: the down alert should arrive within your heartbeat window, followed by the recovery message when the service returns (Better Stack).

How do you build a public Uptime Kuma status page?

Click Status Page in the nav bar, then New Status Page: give it a name and a slug, add a description and footer text, attach the monitors you want visible, and save. Visitors get a live health page with no admin access; check it in an incognito window to see exactly what the public sees (Better Stack).

This is the feature hosted services most often lock behind paid tiers (Matthew Wong). Map the page to a subdomain like status.yourdomain.com so users and clients can check service health themselves instead of asking you.

How do you put Uptime Kuma behind HTTPS?

Bind the container port to localhost (-p 127.0.0.1:3001:3001) and place a reverse proxy such as Nginx in front. The one setting everyone gets wrong: Uptime Kuma's UI runs over WebSocket, so the proxy must forward the Upgrade and Connection headers, or the dashboard shows a loading spinner forever (Matthew Wong; Bitnesia).

Certificate-expiry alerts ride on your HTTP(s) monitors, so your own certificate gets watched by the same system. Running the whole stack in a home lab? Our Proxmox beginner guide covers the host side of that setup.

Uptime Kuma vs UptimeRobot: which should you use?

Choose Uptime Kuma if you own a server and want unlimited checks with full data control; choose UptimeRobot if you want zero maintenance and do not mind the caps. The comparison below uses UptimeRobot's official pricing page (crawled 2026-10-30) against Kuma's self-hosted model.

The honest trade-off: Kuma has no built-in failover — if the machine running it goes down, your monitoring goes blind with it (Better Stack). For anything critical, either run a second Kuma instance elsewhere or keep one cheap hosted check watching the Kuma box itself.

Beginner traps to avoid

The Docker Container monitor type needs -v /var/run/docker.sock:/var/run/docker.sock, and that mount grants root-equivalent access to the Docker daemon. Only add it if you need container monitors, and never expose that dashboard to the public internet (Bitnesia).

Two more traps from the install guides: the latest image tag is legacy v1 — pin :2 — and SQLite corrupts on NFS, so keep the data volume local (Bitnesia). And repeat the golden rule: there is no email password reset, so the admin credentials you create on day one must be stored somewhere you trust (Bitnesia).

Sources

• Bitnesia, "How to Install Uptime Kuma on Docker: Self-Hosted Uptime Monitoring" — https://www.bitnesia.com/en/how-to-install-uptime-kuma-on-docker (fetched 2026-10-30)
• Better Stack, "A Complete Guide to Monitoring With Uptime Kuma" — https://betterstack.com/community/guides/monitoring/uptime-kuma-guide/ (updated 2026-01-23; fetched 2026-10-30)
• Matthew Wong, "Uptime Kuma: Self-Hosted Uptime Monitoring That Just Works" — https://www.matthewswong.com/en/blog/self-hosted-uptime-kuma-monitoring/ (fetched 2026-10-30)
• Lineserve, "How to Self-Host Uptime Kuma for Free Server Monitoring with Docker" — https://www.lineserve.net/tutorials/self-host-uptime-kuma-server-monitoring-docker (fetched 2026-10-30)
• Webnestify, "Uptime Kuma: My Self-Hosted Monitoring Setup" — https://webnestify.cloud/insights/operations-automation/uptime-kuma-self-hosted-monitoring/ (fetched 2026-10-30)
• Edgible Guides, "Uptime monitoring with Uptime Kuma - Website on Edgible" — https://guides.edgible.com/guides/website-on-edgible/05-uptime-kuma.html (fetched 2026-10-30)
• Google page-1 results for "how to use uptime kuma" and "UptimeRobot free plan monitors check interval limit"; UptimeRobot official pricing — https://uptimerobot.com/pricing/ (all fetched 2026-10-30)

Frequently Asked Questions

Is Uptime Kuma really free?

Yes. Uptime Kuma is free and open-source software by Louis Lam with no paid tier and no feature gates. Your only cost is the server you run it on, and 1 vCPU with 1 GB of RAM covers dozens of lightweight monitors (Bitnesia).

What happens if I forget my Uptime Kuma admin password?

There is no email password reset and no reset button in the dashboard. You must reset the credentials from the container's command line, which is why the guides insist on storing the password before you expose the dashboard (Bitnesia).

Can Uptime Kuma check from multiple locations?

Not natively. A single Uptime Kuma instance runs its checks from one machine, so it cannot do the multi-region verification hosted services offer (Better Stack). If location diversity matters, run a second instance in another region or keep one cheap hosted monitor watching the Kuma box.

How many monitors can Uptime Kuma handle?

Dozens of lightweight HTTP and ping monitors run comfortably on 1 vCPU and 1 GB of RAM, and the practical ceiling is your server's resources rather than a license limit (Bitnesia). Very large fleets may eventually need the external MariaDB option that version 2 supports.

Should I use Uptime Kuma or UptimeRobot?

Use Uptime Kuma when you own a server, want unlimited monitors with check intervals down to 20 seconds, and prefer your monitoring data on your own machine. Use UptimeRobot's free tier when you want zero maintenance and 50 monitors at 5-minute intervals is enough (UptimeRobot pricing, 2026-10-30). Many self-hosters run both: Kuma for everything, plus one hosted check watching the Kuma server itself.