How to Self-Host Uptime Kuma Status Page & Server Monitoring on Ubuntu VPS

Why Relying on Paid Status Page Services Is Unnecessary

Maintaining high service availability requires continuous monitoring of your website endpoints, API gateways, database ports, and DNS resolvers. While commercial monitoring SaaS platforms (like Pingdom, Better Uptime, or Statuspage.io) charge $25 to $100+ monthly with strict monitor quantity limits, self-hosting your own monitoring portal gives you unlimited monitors, custom check intervals down to 20 seconds, and branded public status pages at zero recurring cost.

Uptime Kuma is the leading open-source self-hosted monitoring tool. Featuring an intuitive visual interface, Uptime Kuma monitors HTTP/HTTPS endpoints, TCP ports, ping latency, DNS records, Docker container daemons, and Steam game servers. It includes native multi-channel alerting to over 90+ notification services (Discord, Telegram, Slack, Webhooks, SMS, Email) and publishes beautiful, mobile-friendly public status pages for your users.

In this technical tutorial, we will configure Uptime Kuma on Ubuntu 24.04/22.04 LTS with Docker Compose, secure the web portal behind an Nginx reverse proxy with SSL, configure multi-channel alerts, and publish a branded public status page.

Step 1: Installing Docker and Creating Project Directory

# Install Docker and prerequisite utilities
sudo apt update && sudo apt install -y curl nginx certbot python3-certbot-nginx

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# Create dedicated directory for Uptime Kuma
sudo mkdir -p /var/www/uptime-kuma
sudo chown -R $USER:$USER /var/www/uptime-kuma
cd /var/www/uptime-kuma

Step 2: Writing Production Docker Compose File

Create /var/www/uptime-kuma/docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime_kuma
    restart: always
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
    deploy:
      resources:
        limits:
          memory: 256M

volumes:
  kuma_data:

Launch the container in background daemon mode:

docker compose up -d
docker compose ps

Step 3: Nginx Reverse Proxy with Real-Time WebSockets & SSL

Uptime Kuma relies on WebSockets for live status updates. Create /etc/nginx/sites-available/status.example.com:

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;
    }
}

Enable the site configuration and acquire a free Let’s Encrypt SSL certificate:

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Step 4: Configuring Multi-Channel Notifications (Discord / Telegram)

Navigate to Settings > Notifications > Setup Notification in your Uptime Kuma dashboard:

• Telegram Bot: Enter Bot Token and Chat ID to receive instant alerts within 2 seconds of server downtime.
• Discord Webhook: Paste your Discord server channel webhook URL for team operational awareness.
• Custom Webhook: Send automated JSON payloads to internal automation pipelines or n8n workflows to trigger self-healing server restart scripts automatically.

Step 5: Publishing a Public Customer Status Page

Click Status Pages > New Status Page to create a branded public dashboard at https://status.example.com/status/main with custom incident announcement banners, uptime percentage badges, and incident history.

Uptime Kuma Monitoring Protocol Capabilities

Monitoring Internal Docker Containers via Docker Socket

Uptime Kuma can monitor internal Docker container health directly over the Unix socket (/var/run/docker.sock), verifying if container daemons restart or exit unexpectedly without exposing internal ports:

# Mount Docker socket in docker-compose.yml
volumes:
  - ./data:/app/data
  - /var/run/docker.sock:/var/run/docker.sock:ro

In Uptime Kuma, select Monitor Type: Docker Container, and choose any running container from the auto-populated list!

Setting Up Custom Domain SSL Expiry Alerts

Never let an SSL certificate expire unnoticed. Uptime Kuma automatically monitors TLS handshake certificates across all configured HTTPS monitors and triggers warning notifications 14, 7, and 3 days before certificate expiration.

Uptime Kuma Routine Database Backups

Uptime Kuma stores monitor history and incident logs in an embedded SQLite database (kuma.db). Back up this file with a simple nightly cron job: cp /var/www/uptime-kuma/data/kuma.db /var/backups/kuma_$(date +%F).db.

Configuring Push Monitors for Cron Jobs & Background Tasks

In addition to active polling monitors, Uptime Kuma supports Push (Heartbeat) Monitors for verifying that critical background cron jobs (such as nightly database backups or video transcoding queues) execute successfully. The cron script sends an HTTP GET heartbeat upon completion; if Uptime Kuma does not receive the ping within the expected time window, an alert triggers immediately:

# Example: Nightly MySQL Backup with Uptime Kuma Heartbeat Ping
#!/bin/bash
set -e
/usr/local/bin/backup-database.sh

# Send successful heartbeat ping to Uptime Kuma push URL
curl -s -m 10 "https://status.example.com/api/push/kUmApUsHtOkEn123?status=up&msg=OK&ping="

Customizing Status Page CSS & Corporate Branding

Uptime Kuma allows injecting custom CSS rules into public status pages. Match your corporate design system with custom brand colors, glassmorphic cards, custom logo headers, and dark mode toggles directly from the Status Page settings panel.