How to Set Up Uptime Kuma for Service Monitoring

How to Set Up Uptime Kuma for Service Monitoring

Uptime Kuma is a self-hosted monitoring tool that tracks the availability of your websites, APIs, and services. It provides a beautiful dashboard, flexible notifications, and status pages—all running on your Breeze server with minimal resources.

Installing Uptime Kuma with Docker

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

Docker Compose Setup

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    restart: unless-stopped

volumes:
  uptime_kuma_data:

Access the dashboard at http://your-breeze-ip:3001 and create your admin account on first visit.

Adding Monitors

Uptime Kuma supports many monitor types. Here are the most common:

HTTP/HTTPS Monitor

• URL: https://yourdomain.com
• Heartbeat Interval: 60 seconds
• Retries: 3 (avoids false alerts from transient issues)
• Accepted Status Codes: 200-299
• Keyword: optionally check for specific text in the response

TCP Port Monitor

• Hostname: your-breeze-ip
• Port: 3306 (MySQL), 5432 (PostgreSQL), 6379 (Redis), etc.

DNS Monitor

• Hostname: yourdomain.com
• DNS Resolver: 1.1.1.1
• Record Type: A, CNAME, MX, etc.

Docker Container Monitor

Monitor container health by mounting the Docker socket:

docker run -d --name uptime-kuma \
  -p 3001:3001 \
  -v uptime-kuma-data:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  louislam/uptime-kuma:latest

Configuring Notifications

Uptime Kuma supports 90+ notification services. Common options include:

• Email (SMTP) — enter your mail server details for email alerts
• Slack — paste an incoming webhook URL
• Discord — use a Discord webhook for channel alerts
• Telegram — provide your bot token and chat ID
• Webhook — send JSON payloads to any HTTP endpoint

Configure notifications under Settings → Notifications, then assign them to individual monitors or apply them as defaults.

Creating a Public Status Page

1. Navigate to Status Pages in the sidebar
2. Click New Status Page
3. Add your monitors organized by category (Web, API, Database, etc.)
4. Customize the title, description, and logo
5. Share the public URL with your users: http://your-breeze-ip:3001/status/main

Reverse Proxy with Nginx

Put Uptime Kuma behind Nginx with SSL for production use:

server {
    listen 443 ssl;
    server_name status.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/status.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.yourdomain.com/privkey.pem;

    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;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The WebSocket headers (Upgrade and Connection) are essential for Uptime Kuma's real-time dashboard.

Best Practices

• Set heartbeat intervals between 30 and 120 seconds depending on criticality
• Use at least 2 retries before alerting to reduce false positives
• Group related monitors with tags for easier dashboard navigation
• Back up the /app/data volume regularly as it contains all configuration
• Run Uptime Kuma on a separate Breeze instance from the services it monitors