Uptime Kuma¶

Uptime Kuma is a self-hosted monitoring tool for tracking service availability and creating status pages.

Features¶

Multiple monitor types (HTTP, TCP, Ping, DNS, etc.)
Status pages
Notifications (Slack, Discord, Email, etc.)
Multi-language support
Certificate expiration monitoring

Docker Compose Setup¶

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - proxy

networks:
  proxy:
    external: true

Initial Setup¶

Access at http://localhost:3001
Create admin account
Add monitors
Configure notifications

Monitor Types¶

HTTP(s)¶

Monitor web endpoints:

URL: https://example.com
Method: GET
Expected Status: 200
Interval: 60 seconds
Retries: 3

TCP Port¶

Check if a port is open:

Hostname: database.local
Port: 5432
Interval: 60 seconds

Ping¶

ICMP ping check:

Hostname: server.local
Interval: 60 seconds

DNS¶

Monitor DNS records:

Hostname: example.com
DNS Server: 1.1.1.1
Record Type: A
Expected Value: 93.184.216.34

Docker Container¶

Monitor container status:

Container Name: nginx
Docker Host: /var/run/docker.sock

Database¶

Check database connectivity:

MySQL:

Connection String: mysql://user:pass@host:3306/database

PostgreSQL:

Connection String: postgres://user:pass@host:5432/database

MongoDB:

Connection String: mongodb://user:pass@host:27017/database

Keywords¶

Check page contains/doesn't contain text:

URL: https://example.com/status
Keyword: "operational"
Should Contain: Yes

JSON Query¶

Validate JSON API response:

URL: https://api.example.com/health
JSON Path: $.status
Expected Value: "ok"

Status Pages¶

Create Status Page¶

Go to Status Pages
Click New Status Page
Configure:
Title and description
Add monitor groups
Custom domain (optional)

Public URL¶

Status pages are accessible at:

http://uptime-kuma:3001/status/page-slug

Custom Domain¶

Add to your reverse proxy:

# Traefik
labels:
  - "traefik.http.routers.status.rule=Host(`status.example.com`)"

Notifications¶

Discord¶

Create Discord webhook
In Uptime Kuma: Settings > Notifications
Add Discord notification:
Webhook URL: https://discord.com/api/webhooks/...

Slack¶

Webhook URL: https://hooks.slack.com/services/...
Channel: #alerts

Email (SMTP)¶

SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Security: STARTTLS
Username: your@email.com
Password: app-password
From: alerts@example.com
To: admin@example.com

Telegram¶

Bot Token: 123456:ABC-DEF...
Chat ID: -1001234567890

Pushover¶

User Key: your-user-key
API Token: your-api-token

Generic Webhook¶

URL: https://your-webhook-endpoint.com
Method: POST
Headers:
  Content-Type: application/json
Body: {"status": "{{status}}", "monitor": "{{name}}"}

Maintenance Windows¶

Schedule maintenance:

Go to Maintenance
Click Add Maintenance
Configure:
Title
Affected monitors
Start/end time
Recurrence

During maintenance, monitors won't trigger alerts.

Grouping Monitors¶

Create Groups¶

Add group in monitor settings
Group monitors by:
Service type
Environment
Location

Status Page Groups¶

Infrastructure
├── Proxmox
├── TrueNAS
└── Router

Services
├── Jellyfin
├── Nextcloud
└── Pi-hole

External
├── GitHub
└── Cloudflare

API¶

API Token¶

Settings > API Keys
Generate new key

Get Monitors¶

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://uptime-kuma:3001/api/monitors

Get Status¶

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://uptime-kuma:3001/api/status-page/heartbeat/slug

Docker Integration¶

Monitor Containers¶

Mount Docker socket:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Then add Docker Container monitors.

Remote Docker¶

For remote Docker hosts, use TCP:

# On remote host, enable Docker TCP
# /etc/docker/daemon.json
{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2375"]
}

Reverse Proxy¶

Traefik¶

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

Caddy¶

status.example.com {
    reverse_proxy uptime-kuma:3001
}

Backup¶

Export Settings¶

Settings > Backup
Click Export
Save JSON file

Docker Volume Backup¶

# Stop container
docker stop uptime-kuma

# Backup data
tar -czvf uptime-kuma-backup.tar.gz ./data

# Start container
docker start uptime-kuma

Restore¶

Settings > Backup
Click Import
Upload JSON file

High Availability¶

Multiple Instances¶

For redundancy, run multiple instances:

services:
  uptime-kuma-1:
    image: louislam/uptime-kuma:latest
    volumes:
      - ./data-1:/app/data

  uptime-kuma-2:
    image: louislam/uptime-kuma:latest
    volumes:
      - ./data-2:/app/data

Note: Data doesn't sync between instances. Configure same monitors on both.

Troubleshooting¶

Logs¶

docker logs uptime-kuma

Common Issues¶

Monitor shows DOWN incorrectly
Increase retry count
Check network connectivity
Verify URL/hostname is accessible from container
Notifications not sending
Test notification in settings
Check notification service credentials
Verify network access to notification service
High memory usage
Reduce monitor intervals
Limit heartbeat retention

Reset Password¶

docker exec -it uptime-kuma node extra/reset-password.js