DEV Community

Royce
Royce

Posted on • Originally published at ossalt.com

Self-Hosting Guide: Deploy Uptime Kuma for Monitoring

#uptimekuma #monitoring #selfhosting #docker

Self-Hosting Guide: Deploy Uptime Kuma for Monitoring

Uptime Kuma is the most popular open source monitoring tool with 62K+ GitHub stars. It replaces Better Stack, Pingdom, and UptimeRobot. One Docker command gives you monitoring for all your services with 90+ notification channels.

Requirements

  • VPS with 512 MB RAM minimum
  • Docker
  • Domain name (e.g., status.yourdomain.com)
  • 5 GB disk

Step 1: Deploy with Docker 

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

That's it. Uptime Kuma runs on port 3001.

Step 2: Reverse Proxy (Caddy) 

# /etc/caddy/Caddyfile
status.yourdomain.com {
    reverse_proxy localhost:3001
}
Enter fullscreen mode Exit fullscreen mode 
sudo systemctl restart caddy
Enter fullscreen mode Exit fullscreen mode

Step 3: Initial Setup

  1. Open https://status.yourdomain.com
  2. Create your admin account
  3. Start adding monitors

Step 4: Add Monitors

Monitor types available:

Type Use Case
HTTP(s) Website availability, API endpoints
TCP Port Database, Redis, custom services
Ping Server reachability
DNS DNS record verification
Docker Container Container health via Docker socket
Steam Game Server Game server monitoring
MQTT IoT broker monitoring
gRPC gRPC service health
Keyword Check if a page contains specific text
JSON Query Validate API response values
Push Receive heartbeats from your services

Example monitors to set up:

Website:         https://yourdomain.com          (HTTP, 60s interval)
API:             https://api.yourdomain.com/health (HTTP, 30s interval)
Database:        db.internal:5432                 (TCP, 60s interval)
Redis:           redis.internal:6379              (TCP, 60s interval)
Mail server:     mail.yourdomain.com:587          (TCP, 300s interval)
DNS:             yourdomain.com (A record)        (DNS, 300s interval)
Enter fullscreen mode Exit fullscreen mode

Step 5: Configure Notifications

Uptime Kuma supports 90+ notification services. Most popular:

Service Setup
Slack Incoming webhook URL
Discord Webhook URL from channel settings
Telegram Bot token + chat ID
Email (SMTP) Host, port, username, password
PagerDuty Integration key
Pushover User key + app token
Ntfy Topic URL (self-hostable too)
Gotify Server URL + app token

Setting up Discord notifications:

  1. Discord channel → Edit Channel → Integrations → Webhooks
  2. Copy webhook URL
  3. In Uptime Kuma → Settings → Notifications → Setup Notification
  4. Select Discord, paste webhook URL
  5. Set as default notification for all monitors

Step 6: Create Status Pages

  1. Click Status Pages in the sidebar
  2. Create a new status page
  3. Add monitor groups (e.g., "Website", "API", "Infrastructure")
  4. Assign monitors to groups
  5. Customize with your logo and description
  6. Share the public URL with your team or users

Custom domain for status page:

# /etc/caddy/Caddyfile
status.yourdomain.com {
    reverse_proxy localhost:3001
}
Enter fullscreen mode Exit fullscreen mode

Step 7: Docker Socket Monitoring (Optional)

Monitor Docker containers directly:

# Updated docker-compose.yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
Enter fullscreen mode Exit fullscreen mode

Now add monitors of type Docker Container to track container health.

Step 8: Push Monitors for Cron Jobs

For monitoring cron jobs and background tasks:

  1. Create a Push type monitor in Uptime Kuma
  2. Copy the push URL
  3. Add to your cron job: 
# At the end of your cron job
curl -s "https://status.yourdomain.com/api/push/YOUR_PUSH_TOKEN?status=up&msg=OK"
Enter fullscreen mode Exit fullscreen mode

If the push doesn't arrive within the heartbeat interval, Uptime Kuma alerts you.

Production Hardening

Backups:

# Backup SQLite database (daily cron)
docker cp uptime-kuma:/app/data/kuma.db /backups/kuma-$(date +%Y%m%d).db
Enter fullscreen mode Exit fullscreen mode

Updates:

docker pull louislam/uptime-kuma:latest
docker stop uptime-kuma
docker rm uptime-kuma
docker run -d \
  --name uptime-kuma \
  --restart unless-stopped \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  louislam/uptime-kuma:latest
Enter fullscreen mode Exit fullscreen mode

Security:

  • Enable 2FA in account settings
  • Use a strong admin password
  • Put behind reverse proxy with HTTPS
  • Consider restricting dashboard access by IP

Resource Usage

Monitors RAM CPU Disk
1-50 256 MB 1 core 1 GB
50-200 512 MB 1 core 5 GB
200+ 1 GB 2 cores 10 GB

VPS Recommendations

Provider Spec Price
Hetzner 2 vCPU, 2 GB RAM €4.50/month
DigitalOcean 1 vCPU, 1 GB RAM $6/month
Linode 1 vCPU, 1 GB RAM $5/month

Uptime Kuma is extremely lightweight — it can share a VPS with other services easily.

Compare monitoring tools on OSSAlt — features, notification channels, and self-hosting options side by side.

Top comments (0)