Install Uptime Kuma Monitoring on VPS
Home › Install Uptime Kuma Monitoring on VPS

Install Uptime Kuma Monitoring on VPS

June 2026 · 6 min read

Uptime Kuma is a self-hosted uptime monitoring tool that checks websites, TCP ports, DNS records, SSL certificate expiry, and server ping every 20 seconds. When a service goes down, it instantly sends notifications through Line OA, Telegram, Discord, Email, or Webhook. It also provides a public status page that you can share with customers to monitor service availability in real-time.

Install Uptime Kuma with Docker

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

# Verify
docker ps | grep uptime-kuma
# Open http://YOUR_VPS_IP:3001

Set Up Nginx Reverse Proxy + SSL

sudo certbot --nginx -d status.yourdomain.com

sudo nano /etc/nginx/sites-available/uptime-kuma

server {
    listen 443 ssl;
    server_name status.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/status.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

sudo nginx -t && sudo systemctl reload nginx

Add Monitors and Configure Notifications

# Open https://status.yourdomain.com
# 1. Create a user account on first login
# 2. Click "+ Add New Monitor"
# Common monitor types:
#   - HTTP(s): Check website response code
#   - TCP Port: Check if port is open
#   - DNS: Check DNS record
#   - Ping: Check server is online
#   - Certificate Expiry: Alert before SSL expires

# Set up Line notification:
# Settings > Notifications > Line Messenger
# Enter Line Channel Access Token and User ID

Set Up Public Status Page

# Status Pages > Create New Status Page
# Set name and slug (e.g. "status")
# Open https://status.yourdomain.com/status/status
# Add monitors you want to display
# Share URL with customers to view service status anytime

Use Docker Compose for Easy Management

Instead of remembering long docker run commands, storing configuration in a docker-compose.yml file makes deployment, migration, and version control much easier:

# ~/uptime-kuma/docker-compose.yml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data

# Run commands
docker compose up -d          # start
docker compose pull && docker compose up -d   # update to latest version
docker compose logs -f        # view logs
Note: Pin the image to :1 (major version) instead of :latest to prevent breaking changes during auto-pull — Uptime Kuma v2 changed the database engine so you shouldn't jump major versions without backing up first.

Backup Configuration and Recovery

All monitor data, notifications, and history are stored in the data/ volume (SQLite file) — back up regularly to protect against VPS failure:

# Backup the entire data folder (stop container first for SQLite integrity)
docker compose stop
tar czf kuma-backup-$(date +%F).tar.gz data/
docker compose start

# Restore on a new machine
tar xzf kuma-backup-2026-06-14.tar.gz
docker compose up -d
Tip: Deploy monitoring on a separate VPS from the server being monitored so you'll get alerts even if your primary server goes down. If you only have one VPS, use Uptime Kuma Cloud instead.

Verify Uptime Kuma is Working Correctly

# Check container status
docker ps | grep uptime-kuma

# Check port 3001
ss -tlnp | grep 3001

# View logs
docker logs uptime-kuma -f

# Test web access
curl -I https://status.yourdomain.com
Tip: Use Uptime Kuma's push monitor feature for cron jobs that need to run every night. Each time the cron runs, it sends a heartbeat ping. If the ping isn't received, you'll get an alert that the cron job failed.

Common Issues & Troubleshooting

Uptime Kuma doesn't restart after VPS reboot

You need to add --restart unless-stopped to your docker run command or update the container settings:

docker update --restart unless-stopped uptime-kuma

SSL Certificate Expiry monitor is alerting incorrectly

Verify that the domain points to the correct server and port 443 is open. Some servers redirect HTTP to HTTPS, which the monitor must follow:

# Test SSL manually
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 2>/dev/null | \
  openssl x509 -noout -dates

Line notifications are not being received

Line Channel Access Token expires every 30 days. You need to refresh it in the Line Developers Console and update the token in Uptime Kuma notification settings.

Monitor shows "Pending" for an unusually long time

The Uptime Kuma container may be running out of memory. Check memory usage and restart:

docker stats uptime-kuma
docker restart uptime-kuma

Frequently Asked Questions

How many services can Uptime Kuma monitor simultaneously?

There's no hard limit, but checking many monitors frequently in parallel uses significant resources. For a VPS with 1 GB RAM, you can comfortably monitor 50-100 services with 60-second check intervals.

How long does Uptime Kuma keep monitoring data?

Uptime Kuma stores heartbeat history for 30 days by default. You can adjust this in Settings > General > Keep Data Days, but longer retention uses more disk space.

Can I add monitors through an API?

Yes, Uptime Kuma has an unofficial REST API developed by the community called uptime-kuma-api that works with Python and Node.js. It's ideal for automating monitor creation when deploying new services.

Related Articles