Uptime Kuma: The Open-Source Monitoring Tool Practical Guide

What if your website went down right now and you didn't find out until hours later when a frustrated customer emailed support? Downtime is expensive—not just in lost revenue, but in damaged trust. Uptime Kuma is a self-hosted monitoring tool that gives you real-time alerts the moment something goes wrong, and it costs you absolutely nothing.

1. What Is Uptime Kuma?

Uptime Kuma is a self-hosted monitoring tool, similar to UptimeRobot and StatusPage. Its core value proposition: completely free, feature-rich, beautiful UI, and easy to deploy.

Problems It Solves

• Commercial monitoring services are expensive at scale
• Open-source monitoring tools often have clunky interfaces
• Deployment and configuration can be overly complex
• Existing free tools lack comprehensive features

Ideal Use Cases

• Personal website monitoring
• Enterprise service monitoring
• API health checks
• SSL certificate expiration monitoring
• Public status page display

2. Technical Architecture

Tech Stack

• Frontend: Vue 3 + Bootstrap 5
• Backend: Node.js + Express
• Database: SQLite / MariaDB / MySQL / PostgreSQL
• Real-time Communication: Socket.IO
• Notifications: 50+ notification channels

Architecture Highlights

1. Single-file deployment—simple and fast
2. Support for multiple database backends
3. Real-time push notifications with low latency
4. Plugin-based notification system

Monitor Types Overview

┌──────────────────────────────────────┐
│         Uptime Kuma                  │
├──────────────────────────────────────┤
│  HTTP(s)  │  TCP  │  Ping            │
├──────────────────────────────────────┤
│  DNS  │  Push  │  Steam  │  Others   │
└──────────────────────────────────────┘

3. Core Features

HTTP(s) Monitoring

# Capabilities
GET/POST requests
Status code checking
Response body validation
Certificate expiration checking
Custom Headers
Example configuration
URL: https://example.com
Method: GET
Expected Status: 200
Check Certificate: Yes
Max Redirects: 5

TCP Port Monitoring

# Port monitoring
Host: example.com
Port: 80
Timeout: 10 seconds

Use cases
Database servers
SSH services
Game servers
Custom services

Ping Monitoring

# ICMP Ping
Host: 192.168.1.1
Interval: 60 seconds
Packet Size: 64 bytes

Use cases
Server online detection
Network latency monitoring
Bulk host monitoring

DNS Monitoring

# DNS query
Hostname: example.com
Server: 8.8.8.8
Record Type: A
Expected Value: 93.184.216.34

Use cases
DNS resolution monitoring
Domain configuration verification
DNS hijacking detection

Push Monitoring

# Active push — monitored services report their own status

Example
curl https://uptime.example.com/api/push/abc123?status=up&msg=OK

Use cases
Scheduled task monitoring
Script execution monitoring
Internal service monitoring

Notification Channels

# Instant messaging
Telegram
Discord
Slack
WeChat (Enterprise)
DingTalk
Feishu (Lark)
Email
SMTP
Mailgun
SendGrid
SMS
Twilio
Aliyun SMS
Tencent Cloud SMS
Webhook
Custom Webhook
ntfy.sh
Gotify
Pushover
Others
Bark (iOS)
Pushbullet
Google Chat
Matrix

Status Pages

# Features
Custom domain name
Custom themes
Display selected monitors
Real-time status updates
Historical event display
Setup
1. Create a status page
2. Set domain name
3. Select monitors to display
4. Customize styling
5. Publish

Advanced Features

Maintenance Windows:

# Scheduled maintenance

Set maintenance time windows
Pause alerts during maintenance
Auto-resume monitoring
Notify users


Example


Start: 2024-01-01 02:00

End: 2024-01-01 04:00

Description: System upgrade

Affected services: API, Database

Tag System:

# Tag management

Group by type
Categorize by priority
Bulk operations
Quick filtering


Example tags


Production
Staging
Core services
Edge services

4. Deployment Guide

Option 1: Docker Deployment (Recommended)

Quick Start:

# Create data directory

mkdir -p /opt/uptime-kuma/data


Run container
docker run -d \
  --restart=always \
  --name uptime-kuma \
  -p 3001:3001 \
  -v /opt/uptime-kuma/data:/app/data \
  louislam/uptime-kuma:1

Access
http://localhost:3001

Docker Compose (Production):

# docker-compose.yml

version: "3.8"


services:

  uptime-kuma:

    image: louislam/uptime-kuma:1

    container_name: uptime-kuma

    restart: always

    ports:

      - "3001:3001"

    volumes:

      - ./data:/app/data

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

    environment:

      - UPTIME_KUMA_DISABLE_FRAME_SAMEORIGIN=false

      - PUID=1000

      - PGID=1000

# Optional: Nginx reverse proxy

  nginx:

    image: nginx:alpine

    ports:

      - "443:443"

    volumes:

      - ./nginx.conf:/etc/nginx/nginx.conf:ro

      - ./ssl:/etc/nginx/ssl:ro

    depends_on:

      - uptime-kuma

    restart: always

volumes:

  data:

Start the Service:

# Create directory

mkdir -p uptime-kuma/{data,ssl}

cd uptime-kuma


Create config file
vim docker-compose.yml

Start
docker-compose up -d

View logs
docker-compose logs -f uptime-kuma

Access
http://localhost:3001

Option 2: Node.js Deployment

1. Install Node.js

# Install Node.js 18+

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

sudo apt install nodejs


Verify
node -v
npm -v

2. Install PM2

# Install PM2 process manager

sudo npm install -g pm2


Verify
pm2 -v

3. Install Uptime Kuma

# Clone repository

git clone https://github.com/louislam/uptime-kuma.git

cd uptime-kuma


Install dependencies
npm run setup

Build
npm run build

4. Run the Service

# Start with PM2

pm2 start server/server.js --name uptime-kuma


Set up auto-start on boot
pm2 startup
pm2 save

Check status
pm2 status

View logs
pm2 logs uptime-kuma

Option 3: Direct Installation Script

# Download install script
curl -o kuma-install.sh -L https://github.com/louislam/uptime-kuma/raw/master/install.sh

Execute installation
bash kuma-install.sh

Follow the prompts
Choose installation directory
Choose port
Create service

Systemd Service:

# Create service file

sudo vim /etc/systemd/system/uptime-kuma.service


[Unit]

Description=Uptime Kuma

After=network.target

[Service]

Type=simple

User=www-data

WorkingDirectory=/opt/uptime-kuma

ExecStart=/usr/bin/npm run start

Restart=always

RestartSec=10

[Install]

WantedBy=multi-user.target

Enable service
sudo systemctl daemon-reload
sudo systemctl enable uptime-kuma
sudo systemctl start uptime-kuma

5. Comparison with Alternatives

| Feature | Uptime Kuma | UptimeRobot | Pingdom | Better Stack |
|---------|------------|-------------|---------|-------------|
| Price | Free | Freemium | Paid | Paid |
| Open Source | Yes | No | No | No |
| Self-hosted | Yes | No | No | No |
| Monitor Types | HTTP/TCP/Ping/DNS/Push | HTTP/Ping | HTTP/Ping | HTTP/Ping |
| Notifications | 50+ channels | Email only | Email/SMS | Email/Slack |
| Status Pages | Yes (unlimited) | Limited | Paid | Paid |
| Real-time Updates | Yes (WebSocket) | Polling | Polling | Polling |
| SSL Monitoring | Yes | Yes | Paid | Yes |
| Maintenance Windows | Yes | Paid | Paid | Yes |
| Multi-database Support | Yes | N/A | N/A | N/A |

6. Common Issues & Troubleshooting

Issue 1: Notification Delays

# Troubleshooting steps

1. Check network connectivity

   ping the notification server

2. Check rate limits

   Review notification channel limits

3. Optimize configuration

   - Reduce number of monitors

   - Increase monitoring intervals

   - Consolidate notifications

Issue 2: Database Locks (SQLite)

# Resolution

1. Switch to MySQL/MariaDB

2. Increase connection pool

3. Periodically optimize tables

   OPTIMIZE TABLE monitor;

   OPTIMIZE TABLE heartbeat;

Issue 3: High Memory Usage

# Resolution

1. Clean up historical data

   DELETE FROM heartbeat WHERE time < NOW() - INTERVAL 30 DAY;

2. Increase memory limit

   --max-old-space-size=4096

3. Use an external database

7. FAQ

Q: How many monitors can Uptime Kuma handle?
A: With SQLite, it comfortably handles several hundred monitors. For 500+ monitors, consider switching to MySQL or MariaDB for better performance. For 1000+ monitors, you may need to scale horizontally.

Q: Can I monitor services behind a firewall or VPN?
A: Yes. Use the Push monitor type—the internal service actively pushes its status to Uptime Kuma, so no inbound connection is needed. This is ideal for monitoring services that aren't publicly accessible.

Q: Does Uptime Kuma support two-factor authentication (2FA)?
A: Yes, Uptime Kuma supports 2FA. You can enable it in your account settings after logging in.

Q: Can I customize the status page appearance?
A: Yes. You can customize the title, theme (light/dark), and logo. You can also set a custom domain name and choose which monitors to display.

Q: How does Uptime Kuma handle SSL certificate monitoring?
A: Uptime Kuma checks SSL certificates on every HTTPS monitor request. You can set an alert threshold (e.g., 30 days before expiration) to get notified before certificates expire.

Q: Is there a mobile app for Uptime Kuma?
A: Uptime Kuma doesn't have an official mobile app, but its responsive web interface works well on mobile browsers. You can also use push notification services like ntfy.sh or Pushover to receive alerts on your phone.

8. Who Should Use This?

Ideal For:

• Individual developers with personal projects
• Small to medium teams needing reliable monitoring
• Budget-conscious projects
• Self-hosting enthusiasts who want full control
• Teams that need a public status page without paying extra

Not Ideal For:

• Very large-scale monitoring (1000+ monitors) without optimization
• Organizations requiring enterprise-grade SLA reporting
• Teams needing complex APM (Application Performance Monitoring) capabilities
• Environments requiring distributed monitoring across multiple regions

Verdict

Uptime Kuma is a feature-complete, user-friendly open-source monitoring tool. It solves the problem of expensive commercial monitoring services while providing a beautiful interface, 50+ notification channels, and flexible deployment options. For anyone running servers or web services, deploying Uptime Kuma is one of the highest-ROI investments of your time—it will help you catch problems early and minimize downtime.

GitHub Repository: https://github.com/louislam/uptime-kuma