Setting Up Uptime Kuma for Service Monitoring

When you’re self-hosting critical services, you need to know immediately when something goes down. Uptime Kuma is a beautiful, self-hosted monitoring tool that watches your services 24/7.

This guide shows you how to set up Uptime Kuma to monitor everything from websites to Docker containers to API endpoints.

What is Uptime Kuma?

Uptime Kuma is an open-source uptime monitoring and status page tool. Think of it as your personal UptimeRobot or Pingdom, but self-hosted.

Key features:

• Monitor HTTP(s), TCP, ping, DNS, Docker containers
• Beautiful status pages (public or private)
• 14+ notification channels (Discord, Telegram, Email, etc.)
• Response time tracking
• SSL certificate expiration monitoring
• Multi-user support
• Mobile-friendly UI

Why Use Uptime Kuma?

Benefits:

• Know immediately when services go down
• Track response times and performance
• Public status page for users
• Free and self-hosted (no monthly fees)
• No data sharing with third parties

Use Cases:

• Home lab service monitoring
• Website uptime tracking
• API endpoint health checks
• Docker container monitoring
• SSL certificate expiration alerts

Docker Setup

Create docker-compose.yml:

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=America/New_York

Start Uptime Kuma:

docker-compose up -d

Access: http://your-server-ip:3001

Initial Setup

1. Create admin account (username + password)
2. Set up your dashboard
3. You’re ready to add monitors!

Adding Your First Monitor

HTTP(S) Monitor

Monitor a website or web service:

1. Click Add New Monitor
2. Monitor Type: HTTP(s)
3. Friendly Name: “My Website”
4. URL: https://example.com
5. Heartbeat Interval: 60 seconds
6. Retries: 3
7. Save

Uptime Kuma will check every 60 seconds. If it fails 3 times, you’ll get notified.

TCP Port Monitor

Check if a specific port is open:

1. Monitor Type: TCP Port
2. Hostname: 192.168.1.100
3. Port: 22 (SSH example)
4. Interval: 60 seconds

Ping Monitor

Basic ICMP ping check:

1. Monitor Type: Ping
2. Hostname: 192.168.1.100
3. Interval: 30 seconds

Docker Container Monitor

Check if container is running:

1. Monitor Type: Docker Container
2. Docker Host: (requires Docker socket mount)
3. Container Name: plex

Note: Requires Docker socket access (see Advanced section).

Setting Up Notifications

Get instant alerts when services go down.

Discord Notification

1. Settings → Notifications → Setup Notification
2. Type: Discord
3. Discord Webhook URL: (from Discord server settings)
4. Test and Save

Telegram Notification

1. Create bot with @BotFather
2. Get bot token
3. Get your Chat ID: @userinfobot
4. Add notification:
   • Type: Telegram
   • Bot Token: (from BotFather)
   • Chat ID: (your user ID)

Email Notification

1. Type: SMTP Email
2. Hostname: smtp.gmail.com (or your SMTP server)
3. Port: 587
4. Username: your email
5. Password: app password (for Gmail)
6. From/To addresses

Other Notification Options

Uptime Kuma supports 14+ channels:

• Slack
• Teams
• Webhooks
• Pushover
• Gotify
• Signal
• Matrix
• PagerDuty
• And more…

Creating a Status Page

Share uptime status with others (or just for yourself):

1. Status Pages → Add New Status Page
2. Slug: status (URL will be /status/status)
3. Title: “My Services”
4. Select monitors to display
5. Save

Public vs Private:

• Public: Anyone can view
• Private: Requires password

Access: http://your-server-ip:3001/status/status

Advanced Monitoring

Keyword Monitoring

Check if specific text exists on a page:

1. Monitor Type: HTTP(s) - Keyword
2. URL: https://example.com
3. Keyword: “Welcome”
4. If keyword is missing, alert triggers

JSON Query Monitoring

Check API responses:

1. Monitor Type: HTTP(s) - JSON Query
2. URL: https://api.example.com/health
3. JSON Path: $.status
4. Expected Value: "ok"

Certificate Monitoring

Get alerts before SSL certificates expire:

1. Monitor Type: HTTP(s)
2. Enable Certificate Expiry Notification
3. Days before expiry: 14

Uptime Kuma will alert you 14 days before your SSL cert expires.

Docker Container Monitoring (Advanced)

To monitor Docker containers, mount the Docker socket:

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Add this
    environment:
      - TZ=America/New_York

Security Note: Mounting Docker socket gives Uptime Kuma full access to Docker. Only do this if you trust the container.

Reverse Proxy Setup

Make Uptime Kuma accessible via domain: https://status.yourdomain.com

Nginx Proxy Manager

1. Add Proxy Host
2. Domain: status.yourdomain.com
3. Forward to: uptime-kuma:3001
4. Enable SSL (Let’s Encrypt)

Traefik Labels

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.uptime-kuma.rule=Host(`status.yourdomain.com`)"
      - "traefik.http.routers.uptime-kuma.entrypoints=websecure"
      - "traefik.http.routers.uptime-kuma.tls.certresolver=letsencrypt"
      - "traefik.http.services.uptime-kuma.loadbalancer.server.port=3001"

Best Practices

Monitor Intervals

Recommendation:

• Critical services: 30-60 seconds
• Normal services: 300 seconds (5 minutes)
• Non-critical: 600 seconds (10 minutes)

More frequent = more resource usage and network requests.

Notification Groups

Group monitors by criticality:

• Critical → Telegram/SMS (instant)
• Warning → Email (less urgent)
• Info → Discord (awareness)

Maintenance Mode

Use Maintenance Mode during planned downtime to pause alerts:

1. Monitor → Edit
2. Enable Maintenance
3. Set duration
4. Notifications paused during maintenance

Multi-User Setup

Share monitoring dashboard with team members:

1. Settings → Security
2. Enable Disable Auth (if safe internal network) OR
3. Create individual accounts:
   • Settings → Manage Users
   • Add user with password

Backup & Restore

Backup

Data is stored in ./data/kuma.db (SQLite database)

# Backup database
docker-compose exec uptime-kuma cp /app/data/kuma.db /app/data/backup.db

# Copy to host
docker cp uptime-kuma:/app/data/backup.db ./backup.db

Restore

# Stop container
docker-compose down

# Replace database
cp backup.db ./data/kuma.db

# Start container
docker-compose up -d

Automated Backups

# Add to crontab
0 2 * * * docker cp uptime-kuma:/app/data/kuma.db /backups/kuma-$(date +\%Y\%m\%d).db

Monitoring Uptime Kuma Itself

Meta-monitoring: Monitor the monitor.

Option 1: External Service

Use a free external service (UptimeRobot, Hetrix Tools) to monitor your Uptime Kuma instance.

Option 2: Healthchecks.io

Set up a cron job that pings healthchecks.io if Uptime Kuma is running:

*/5 * * * * curl -fsS -m 10 --retry 5 -o /dev/null https://hc-ping.com/your-uuid

Troubleshooting

Monitor Shows “Down” but Service Works

Check:

• Network connectivity from Uptime Kuma container
• Firewall rules
• DNS resolution
• SSL certificate validity

High Resource Usage

Solutions:

• Increase monitor intervals (less frequent checks)
• Reduce number of monitors
• Allocate more RAM to container

Notifications Not Sending

Check:

• Notification channel configuration (test it)
• Network access from container
• Rate limits (Discord, Telegram have limits)

Database Corruption

# Stop container
docker-compose down

# Restore from backup
cp backup.db ./data/kuma.db

# Restart
docker-compose up -d

Performance Optimization

Reduce Database Size

Old data accumulates over time:

1. Settings → Maintenance
2. Set data retention period: 90 days
3. Old data will be auto-purged

Use Prometheus/Grafana (Advanced)

Export metrics to Prometheus for long-term storage:

1. Settings → Export
2. Enable Prometheus export
3. Scrape endpoint: /metrics

Alternatives to Uptime Kuma

• Uptime Robot - Cloud-based (free tier limited)
• Netdata - Real-time system monitoring (more complex)
• Statping - Similar to Uptime Kuma (less active development)
• Cachet - Status page only (no monitoring)

Why Uptime Kuma? Best balance of features, ease of use, and active development.

Example Monitoring Setup

Home Lab:

• Plex (HTTP every 60s)
• Nextcloud (HTTP every 60s)
• Pi-hole (HTTP + DNS every 120s)
• Router (Ping every 30s)
• Internet connectivity (Ping 8.8.8.8 every 60s)
• SSL certificates (Check 14 days before expiry)

Notifications:

• Critical services → Telegram
• Warnings → Discord
• Status page → Public for family

Conclusion

Uptime Kuma gives you peace of mind. Your services are monitored 24/7, and you’ll know immediately when something breaks—whether you’re home or away.

Set it up once, sleep better every night.

Next Steps

1. Set up Docker deployment
2. Add your first monitors (start with critical services)
3. Configure notifications (Telegram/Discord recommended)
4. Create a status page
5. Set up automated backups

Monitoring with Uptime Kuma? Share your setup in the comments!