How to install Uptime Kuma for basic monitoring

Actualizado: 2026-05-03

Uptime Kuma is probably the most popular open-source self-hosted uptime monitor available today. Born in 2021 as a personal project by Louis Lam, it has grown to more than 60,000 stars on GitHub, 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:1.23.16, 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.

Initial basic configuration

On first entry, three things are worth adjusting:

1. Time zone under Settings → General; it defaults to UTC and should be set to Europe/Madrid if you operate from here.
2. Two-factor authentication in Settings → Security with Google Authenticator, Authy or 1Password: an important defensive layer.
3. 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:

1. Talk to @BotFather on Telegram, follow instructions, and note the token it gives.
2. 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.
3. 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:

1. In your Discord server: channel settings → Integrations → Webhooks → New webhook. Copy the webhook URL.
2. 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 (roughly 30 per minute). 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

1. Not configuring backup — Uptime Kuma stores everything in /app/data; if that volume is lost, you lose all configuration and history.
2. 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.
3. 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.
4. Too-aggressive intervals — checking 100 monitors every 10 seconds generates heavy load; 60 seconds is reasonable for most cases.

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.