Updated: 2026-07-07

Uptime Kuma is probably the most used open-source self-hosted uptime monitor today. Born in 2021 as a personal project by Louis Lam, it has grown to close to 89,000 stars on GitHub[1], an active community, and production deployments in thousands of small and mid-sized organizations. This guide covers how to install it with Docker reasonably, configure basic monitors, wire up Telegram and Discord notifications, and the operational mistakes that are easy to make the first time.

Key takeaways

  • Uptime Kuma fills the gap between "set up Prometheus + Blackbox Exporter + Alertmanager" and "pay 50 euros a month to UptimeRobot."

  • A ~200 MB container covers HTTP, TCP, ping, DNS, SSL, gRPC checks and over 90 notification channels.

  • Configure backup from day one: all state lives in /app/data; if that volume is lost, all configuration is gone.

  • Don’t leave the interface exposed without HTTPS or strong authentication: Kuma stores sensitive notification credentials.

  • Validate alerts with an artificial monitor that fails on purpose before trusting the real flow works.

What Uptime Kuma is and what to expect

Uptime Kuma is a web application written in Node.js that monitors service availability through periodic checks and notifies when it detects failures. It supports a wide variety of check types:

  • HTTP/HTTPS with response-code and body-content validation.

  • ICMP ping, open TCP ports, DNS queries.

  • SQL queries against databases, gRPC endpoints.

  • SSL certificates about to expire.

  • Over a dozen additional types.

The pragmatic pitch: fill the gap between "set up Prometheus plus Blackbox Exporter plus Alertmanager with hand-written rules" and "pay 50 euros a month to UptimeRobot." For teams with between five and a hundred services to monitor, it’s the most reasonable choice. Installation takes ten minutes, configuration is visual without YAML or code, and a 200 MB container covers the whole use case.

Prerequisites

  • A server with Docker installed. Any recent Linux distribution works; Debian 13 or Ubuntu 24.04 for stability.

  • Minimal resources: with 100 active monitors, Kuma uses about 200 MB of RAM and under 5% of one CPU core. Any modest VPS (1 vCPU, 1 GB RAM) is enough.

  • Storage: with 60-second checks across 50 monitors, the database grows about 100 MB per month. Plan for at least 10 GB dedicated to Kuma for a long history.

  • If exposing Kuma to the internet, you need a domain, a reverse proxy (nginx, Caddy or Traefik) and valid SSL certificates.

Docker installation

The recommended way is Docker Compose with a small configuration file. Pin the image to louislam/uptime-kuma:2.4.0 (also published on Docker Hub[2]), bind a volume to local ./data, expose port 3001, add a health check, and set a 512M memory cap. Save it as docker-compose.yml and bring it up with docker compose up -d. Open the browser at http://your-server:3001 and you’ll see the admin user creation screen. Pick a strong username and password: Uptime Kuma has no direct password recovery and regaining access requires editing the database manually.

The 2.x line has been the stable branch since October 2025, when 1.23.17 closed out the 1.x series as its last maintenance release; for a new install, 2.x (image louislam/uptime-kuma:2, or a pinned version like 2.4.0) is the recommended choice. Notable additions include MariaDB support as an alternative to the default embedded SQLite database, useful once you go past a few hundred monitors. Multi-user support exists but is still limited: monitors created by one user are not visible to others, so in practice it still works best as a single-admin panel or a small team with shared access.

Initial basic configuration

On first entry, three things are worth adjusting:

  • Time zone under Settings → General; it defaults to UTC and should be set to Europe/Madrid if you operate from here.

  • Two-factor authentication in Settings → Security with Google Authenticator, Authy or 1Password: an important defensive layer.

  • If Kuma sits behind a reverse proxy, check "Trust proxy headers" in General, without which recorded client IPs are the proxy’s and not the real ones.

Creating the first monitors

For each monitor, think in three axes: what I check (endpoint), how often (interval), and what counts as failure (conditions).

For public websites, the standard check is HTTP with a 60-second interval. Verify at least the response code and optionally that the body contains a specific string. The latter is key: a monitor that only checks for 200 doesn’t detect when your application returns a pretty error page with code 200.

For internal TCP-exposed services use the Port type; for SSL certificates about to expire there’s a specific type worth configuring with a 21-day threshold.

Group monitors with coherent tags by criticality (critical, important, informational) and by system. That way you can filter in dashboards and route distinct notifications to distinct channels by severity.

Configuring Telegram notifications

Telegram is one of the most comfortable notification channels:

  • Talk to @BotFather on Telegram, follow instructions, and note the token it gives (the process is described in Telegram’s official bot documentation[3]).

  • Open a conversation with the bot, send /start, then check https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates to see the chat ID. For a group, add the bot to the group and do the same trick.

  • In Uptime Kuma: Settings → Notifications → Add → Telegram. Paste the token and chat ID, test with the "Test" button.

Assign notifications from group tags, not monitor by monitor, to keep configuration manageable.

Configuring Discord notifications

Discord uses incoming webhooks:

  • In your Discord server: channel settings → Integrations → Webhooks → New webhook. Copy the webhook URL.

  • In Uptime Kuma: Notifications → Add → Discord. Paste the URL and choose optional name and avatar. Test and assign to desired monitors.

One detail worth knowing: Discord limits message frequency per webhook to 30 per minute, per its rate limits documentation[4]. If you have 100 monitors and they all fail at once, Discord may start rejecting messages and you’ll lose alerts. For serious production with many monitors, consider grouping notifications using an intermediary like ntfy.sh.

Public status page

In the sidebar: Status Pages → Add New. Choose which monitors to show, the theme, and domain.

The recommended practice is at least two pages:

  • A public one with user-facing services.

  • An internal one with all monitors including internal ones. This lets you communicate status to clients without revealing infrastructure detail.

Common mistakes to avoid

  • Not configuring backup: Uptime Kuma stores everything in /app/data; if that volume is lost, you lose all configuration and history.

  • Leaving the interface exposed without HTTPS or strong authentication: Kuma handles sensitive credentials. Exposing it with a weak-password admin hands over an entry point to your infrastructure.

  • Not validating notifications: after configuring Telegram or Discord, test with an artificial monitor that fails on purpose. Don’t trust it’s working because you saw the test message; the real "monitor fails, alert sent" flow has more pieces.

  • Too-aggressive intervals: checking 100 monitors every 10 seconds generates heavy load; 60 seconds is reasonable for most cases.

Frequently asked questions

Is Uptime Kuma free?

Yes. It is open-source software under the MIT license, with no license cost and no monitor limit. The only real expense is the server you run it on.

What happens if the server running Uptime Kuma goes down?

You stop receiving alerts for as long as the outage lasts, because the monitor cannot watch itself. If monitoring is critical, an independent external heartbeat (another Kuma instance on a different provider, or a third-party status service) that tells you when Kuma itself stops responding is worth setting up.

Does it support multiple users with different permissions?

There is an admin account and you can create additional accounts, but per-monitor access control is still limited: monitors created by one user are not automatically visible to another. In practice it still works best as a single-admin panel or a small team with shared access.

Conclusion

Uptime Kuma is a notably well-made tool for a bounded problem. It doesn’t try to be Grafana, it doesn’t try to be Prometheus with complex rules, it doesn’t manage application metrics. It does one thing (check if your things are alive and alert you if not) with enough simplicity that a small team can maintain it without spending significant time.

For a team just entering serious monitoring, Uptime Kuma is probably the best first piece to install before anything else. It gives you immediate basic coverage, teaches you the discipline of thinking about what deserves monitoring, and when the time comes to add deeper observability, Kuma will keep covering its layer without interfering. It simply does its job and disappears from the radar until something fails, which is exactly what you ask of an uptime monitor.

Read the Spanish version of this article: Cómo instalar Uptime Kuma para monitorización básica.

Sources

  1. GitHub
  2. Docker Hub
  3. Telegram’s official bot documentation
  4. rate limits documentation