Uptime Kuma: Self-Hosted Uptime Monitoring for Servers and APIs

Uptime Kuma is a lightweight, self-hosted monitoring tool with a polished web UI. It checks whether your websites, APIs, databases, and servers are reachable — and alerts you when they are not. Unlike heavyweight APM suites, Uptime Kuma focuses on availability: HTTP status codes, response times, TCP port checks, DNS resolution, and ICMP ping. For most teams, that is the first layer of observability that catches outages before customers do.

This guide deploys Uptime Kuma with Docker on a Linux server, configures monitors for typical infrastructure targets, sets up Telegram notifications, and publishes a public status page. The entire setup takes under 30 minutes and runs comfortably on a small VPS.

Uptime Kuma vs Prometheus/Grafana

These tools complement each other rather than compete. Prometheus collects detailed metrics (CPU, memory, request rates). Uptime Kuma answers a simpler question: "Is the service up and responding correctly from outside?" Use Uptime Kuma for external availability checks and Prometheus for internal capacity planning and performance analysis.

• Uptime Kuma — synthetic checks, status pages, simple alerting, minimal setup.
• Prometheus + Grafana — metrics, dashboards, complex alerting rules, higher setup cost.
• Together — Kuma pages you when the site is down; Grafana shows why it went down.

Prerequisites

• Linux server with Docker and Docker Compose installed
• Domain or subdomain for the dashboard (e.g. status.example.com)
• Reverse proxy (Nginx or Caddy) for HTTPS on the dashboard
• Telegram bot token or Slack webhook for notifications

Step 1: Create Docker Compose Stack

sudo mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma
sudo tee docker-compose.yml >/dev/null <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
[...]

Step 2: Put HTTPS in Front with Caddy

# Add to /etc/caddy/Caddyfile:
status.example.com {
    reverse_proxy 127.0.0.1:3001
}

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Step 3: Initial Setup in the Web UI

Open https://status.example.com and create your admin account. Use a strong password and store it in your password manager. Enable two-factor authentication under Settings → Security if available in your version.

Step 4: Add HTTP Monitors

Create monitors for each critical endpoint. Use keyword checks for APIs that should return specific content, not just HTTP 200.

• Main website — HTTPS, interval 60s, expected status 200.
• API health — https://api.example.com/health, keyword "ok".
• Admin panel — HTTPS, interval 120s, alert only on sustained failure.
• CDN origin — direct check bypassing CDN to detect origin failures.

Step 5: Add TCP and Ping Monitors

HTTP checks do not cover everything. Monitor database ports, mail servers, and raw connectivity with TCP and ping monitors.

• PostgreSQL — TCP monitor on db.example.com:5432.
• Redis/Valkey — TCP monitor on port 6379 (internal host only).
• SMTP — TCP monitor on port 587.
• Server reachability — Ping monitor for each production host.

Step 6: Configure Telegram Alerts

# Create a Telegram bot via @BotFather and get the token.
# Get your chat ID by messaging the bot and calling:
# https://api.telegram.org/bot<TOKEN>/getUpdates

# In Uptime Kuma UI:
# Settings → Notifications → Setup Notification → Telegram
# Paste bot token and chat ID
# Send test notification

Step 7: Tune Retry and Alert Thresholds

Avoid alert fatigue by requiring multiple consecutive failures before notifying. A single timeout during a deploy should not page the on-call engineer at 3 AM.

• Set Retries to 2–3 before marking a monitor down.
• Use Heartbeat interval of 60s for critical services, 300s for low-priority.
• Configure notification cooldown to prevent duplicate alerts during flapping.
• Group related monitors (e.g. all API endpoints) for consolidated status page sections.

Step 8: Publish a Public Status Page

Status pages reduce support tickets during incidents. Customers check the page instead of emailing support. Uptime Kuma generates a hosted status page you can embed or link from your footer.

# In Uptime Kuma UI:
# Status Pages → New Status Page
# Add monitors: Website, API, Database
# Set slug: "trivox" → public URL: status.example.com/status/trivox
# Enable "Show Tags" and custom domain if desired

Step 9: Backup the Data Volume

# Uptime Kuma stores all config in ./data
sudo tar czf /backup/uptime-kuma-$(date +%F).tar.gz -C /opt/uptime-kuma data

# Restore:
# sudo docker compose down
# sudo tar xzf /backup/uptime-kuma-2026-07-01.tar.gz -C /opt/uptime-kuma
# sudo docker compose up -d

Step 10: Monitor Uptime Kuma Itself

The watcher must be watched. Use an external service (a second Uptime Kuma instance, Hetrix, or a simple cron curl from another server) to verify your primary monitor is alive.

Production Checklist

• Bind container port to 127.0.0.1 only — expose via reverse proxy with TLS.
• Back up /opt/uptime-kuma/data daily.
• Document which monitors map to which on-call runbooks.
• Review monitor list quarterly — remove decommissioned services.
• Test alert delivery monthly with a deliberate monitor pause.

"Availability monitoring is only useful when alerts are trusted — tune retries and cooldowns so every notification means action, not noise."