Uptime Kuma Installation for Status Monitoring

Uptime Kuma is a lightweight, self-hosted monitoring tool with a beautiful web interface for monitoring website availability and service status. It supports multiple monitoring types including HTTP, TCP, DNS, ICMP ping, and many others. This guide covers Docker installation, monitor configuration, notification setup, and status page creation.

Introduction
System Requirements
Docker Installation
Initial Setup
Monitor Types
Notification Channels
Status Pages
Advanced Features
Backup and Recovery
Performance Tuning
Troubleshooting
Conclusion

Introduction

Uptime Kuma provides simple yet comprehensive endpoint monitoring with real-time status pages. Unlike complex enterprise monitoring systems, Uptime Kuma focuses on website and service availability with an intuitive interface. It can be deployed in minutes and scales from monitoring a few endpoints to thousands.

System Requirements

Docker and Docker Compose (or standalone Linux/Windows)
At least 512MB RAM
1GB disk space (scales with history retention)
Internet connectivity for external monitoring
Ports 3001 (UI) and optionally 443 (HTTPS)
Optional: Reverse proxy for external access

Docker Installation

Step 1: Install Docker and Docker Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker-compose --version

Step 2: Create Docker Compose File

mkdir -p ~/uptime-kuma
cd ~/uptime-kuma

cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma-data:/app/data
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
    networks:
      - monitoring

volumes:
  uptime-kuma-data:
    driver: local

networks:
  monitoring:
    driver: bridge
EOF

Step 3: Start Uptime Kuma

# Start service
docker-compose up -d

# Verify container is running
docker-compose ps

# View logs
docker-compose logs -f uptime-kuma

Step 4: Access Web Interface

Navigate to http://localhost:3001 and complete initial setup:

Create admin account
Set system name and description
Configure basic settings

Initial Setup

Admin Configuration

# Access container shell
docker exec -it uptime-kuma bash

# View data directory
ls -la /app/data/

# Check logs
tail -f /app/data/uptime-kuma.log

Reverse Proxy Configuration (Nginx)

sudo tee /etc/nginx/sites-available/uptime-kuma > /dev/null << 'EOF'
upstream uptime-kuma {
    server localhost:3001;
}

server {
    listen 443 ssl http2;
    server_name status.example.com;

    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;

    client_max_body_size 10M;

    location / {
        proxy_pass http://uptime-kuma;
        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;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

server {
    listen 80;
    server_name status.example.com;
    return 301 https://$server_name$request_uri;
}
EOF

sudo nginx -t
sudo systemctl restart nginx

Monitor Types

HTTP/HTTPS Monitoring

Via web interface: Add New Monitor > HTTP(s)

Configuration:

Name: Google Homepage
URL: https://www.google.com
Method: GET
Expected Status Code: 200
Interval: 60 seconds
Timeout: 20 seconds
Retries: 0

Advanced options:

Headers: Add custom headers
Body: Check response body contains text
Ignore TLS Error: Enable for self-signed certificates
Basic Auth: Provide credentials

TCP Port Monitoring

Monitor specific TCP ports for service availability:

Name: Database Server
Type: TCP
Hostname: 192.168.1.50
Port: 5432
Interval: 60 seconds
Timeout: 20 seconds

DNS Monitoring

Check DNS record resolution:

Name: DNS Resolution Check
Type: DNS
URL: example.com
Timeout: 10 seconds
Query Type: A
Expected Value: 93.184.216.34

ICMP Ping Monitoring

Ping hosts to check availability:

Name: Server Ping Check
Type: PING
Hostname: 192.168.1.10
Interval: 60 seconds
Timeout: 10 seconds

Keyword/Body Content Monitoring

Name: API Response Check
Type: HTTP(s)
URL: https://api.example.com/health
Method: GET
Keyword: "healthy"
Interval: 30 seconds
Timeout: 10 seconds

Certificate Expiration Monitoring

Name: SSL Certificate Check
Type: HTTP(s)
URL: https://example.com
Check Certificate: true
Days until expiry alert: 30

Creating Monitors via API

# Login to get token
TOKEN=$(curl -X POST http://localhost:3001/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}' \
  | jq -r '.token')

# Create HTTP monitor
curl -X POST http://localhost:3001/api/add-monitor \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "API Endpoint",
    "type": "http",
    "url": "https://api.example.com/health",
    "method": "GET",
    "interval": 60,
    "timeout": 10,
    "retries": 3,
    "maxretries": 3,
    "expectedValue": "200",
    "expectedStatus": "200"
  }'

Notification Channels

Email Notifications

Settings > Notifications > Add Notification

Type: Email
SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Username: [email protected]
SMTP Password: app-password
From Email: [email protected]
To Email: [email protected]
TLS: Enable
Test: Send test email

Slack Integration

Type: Slack
Slack Webhook URL: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Channel: #monitoring
Bot Name: Uptime Kuma
Icon Emoji: :robot_face:
Status: Online/Offline/Down
Test: Send test message

Discord Integration

Type: Discord
Webhook URL: https://discord.com/api/webhooks/YOUR/WEBHOOK
Username: Uptime Kuma
Avatar URL: https://example.com/avatar.png
Test: Send test notification

Telegram Integration

Type: Telegram
Chat ID: -1001234567890
Telegram Bot Token: YOUR_BOT_TOKEN
Format: Message/HTML
Test: Send test notification

PagerDuty Integration

Type: PagerDuty
Integration Key: YOUR_INTEGRATION_KEY
Service Key: YOUR_SERVICE_KEY
Severity: critical/error/warning/info
Test: Send test alert

Custom Webhook

Type: Webhook
URL: https://your-api.example.com/alerts
Method: POST
Content Type: application/json
Custom Body: 
{
  "alert": "{{ title }}",
  "status": "{{ status }}",
  "monitor": "{{ monitorName }}",
  "timestamp": "{{ now() }}"
}

Assign Notifications to Monitors

Edit Monitor
Notifications tab
Enable notifications for specific channels
Select when to notify (down, up, both)

Status Pages

Create Public Status Page

Settings > Status Pages
Create Status Page
Name: "System Status"
Domain: status.example.com
Description: "Real-time system status"

Configure Status Page

General:
- Page Title: Company Status
- Description: Official status page
- Footer Text: Powered by Uptime Kuma
- Show Tags: Enable
- Show Certificates: Enable

Appearance:
- Theme: Light/Dark
- Header Color: #000000
- Icon: Upload custom logo

Monitors:
- Add monitors to display
- Set monitor groups
- Customize order

Public Status Page Access

Public status page URL: http://localhost:3001/status/page-slug

Embed on website:

<iframe 
  src="http://status.example.com/" 
  style="width:100%; height:600px; border:none;">
</iframe>

Advanced Features

Monitor Groups

Organize monitors by category:

1. Settings > General
2. Create Groups: Infrastructure, Applications, APIs
3. Assign monitors to groups
4. Reorder on status page

Maintenance Windows

Schedule downtime:

1. Maintenance > Add Maintenance
2. Title: Database Upgrade
3. Description: Scheduled maintenance
4. Date/Time: 2024-01-15 02:00 - 04:00 UTC
5. Monitors: Select affected monitors
6. Status Page: Show on status page

Tag System

Organize monitors with tags:

1. Create Tags:
   - production
   - external
   - critical
   - monitoring

2. Assign to monitors:
   - Helps with filtering
   - Useful for status pages

Custom Domain Configuration

# Docker Compose update
docker-compose stop
docker-compose pull

# Update volumes if needed
docker-compose up -d

# Set custom domain in settings
# Settings > General > Domain > status.example.com

Database Management

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

# View database path
docker exec uptime-kuma ls -la /app/data/

# Database file
/app/data/kuma.db  # SQLite database

Backup and Recovery

Docker Volume Backup

# Create backup
docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/app/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/uptime-kuma-backup.tar.gz -C /app/data .

# List backups
ls -lh uptime-kuma-backup.tar.gz

# Restore backup
docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/app/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/uptime-kuma-backup.tar.gz -C /app/data

Export Configuration

# Via API
curl -X GET http://localhost:3001/api/monitors \
  -H "Authorization: Bearer $TOKEN" > monitors.json

curl -X GET http://localhost:3001/api/status-pages \
  -H "Authorization: Bearer $TOKEN" > status-pages.json

Database Export

# SQLite dump
docker exec uptime-kuma sqlite3 /app/data/kuma.db ".dump" > database.sql

# Verify
sqlite3 kuma.db "SELECT COUNT(*) FROM monitor;"

Performance Tuning

Increase Check Interval

For development/testing, reduce check frequency:

Monitor > Edit > Interval: 300 seconds (default 60)

Connection Pooling

Edit monitor settings:

Timeout: 30 seconds
Retries: 2
Maxretries: 5

Database Optimization

# Clean old records
docker exec uptime-kuma sqlite3 /app/data/kuma.db \
  "DELETE FROM heartbeat WHERE time < datetime('now', '-90 days');"

# Vacuum database
docker exec uptime-kuma sqlite3 /app/data/kuma.db "VACUUM;"

Troubleshooting

Check Container Status

# View container status
docker-compose ps

# Check logs
docker-compose logs uptime-kuma

# View specific error
docker-compose logs uptime-kuma | grep -i error

Test Monitor Connection

# Test HTTP
curl -I https://example.com

# Test TCP
telnet 192.168.1.50 5432

# Test DNS
nslookup example.com

# Test Ping
ping -c 4 192.168.1.10

API Debugging

# Test API endpoint
curl -X GET http://localhost:3001/api/monitors \
  -H "Authorization: Bearer $TOKEN"

# Check API errors
docker-compose logs uptime-kuma | grep "API\|error"

Notification Issues

# Test notification channel
Settings > Notifications > Test

# Check notification logs
docker-compose logs uptime-kuma | grep -i notification

# Verify webhook connectivity
curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK \
  -H 'Content-type: application/json' \
  -d '{"text":"Test message"}'

Conclusion

Uptime Kuma provides a simple yet powerful solution for endpoint and service monitoring with beautiful status pages. By following this guide, you've deployed a self-hosted monitoring platform that scales from small deployments to enterprise use. Focus on setting up comprehensive notification channels, regularly reviewing monitor coverage, and leveraging status pages for customer communication. The combination of multiple monitor types, flexible notifications, and public status pages creates a complete availability monitoring solution.

Uptime Kuma installation for status monitoring