Uptime Kuma: Self-Hosted Service Monitoring

Uptime Kuma is the easiest way to monitor your self-hosted services. It checks URLs, ports, DNS records, and APIs at configurable intervals, sends alerts through dozens of notification channels, and hosts a public status page. Docker installation takes five minutes.

Photo by Jonathan Castañeda on Unsplash

What Uptime Kuma Monitors

• HTTP/HTTPS: URL monitoring with status code and keyword checks
• TCP port: Check if a port is open on a host
• Ping: ICMP ping checks
• DNS: DNS record monitoring
• Docker container: Check container health status
• Database: PostgreSQL, MySQL, MariaDB, Redis connectivity
• MQTT: IoT messaging protocol
• Steam game server: Steam Server Query protocol
• JSON query: Parse JSON responses and check values

Docker Deployment

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - 3001:3001
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

docker compose up -d

Navigate to http://your-server:3001. First visit prompts you to create an admin account.

Adding Monitors

Click Add New Monitor:

HTTP(s) monitor (most common):

• Monitor Type: HTTP(s)
• Friendly Name: "Paperless-NGX"
• URL: https://paperless.yourdomain.com
• Heartbeat Interval: 60 (check every 60 seconds)
• Retries: 1 (retry once before alerting)
• HTTP keyword check: optional — check response body for specific text

TCP Port monitor (for non-HTTP services):

• Monitor Type: TCP Port
• Host: 192.168.1.50
• Port: 5432 (PostgreSQL)

Docker container monitor:

• Monitor Type: Docker Container
• Docker Container: select container name
• Requires the Uptime Kuma container to have Docker socket access

volumes:
  - /var/run/docker.sock:/var/run/docker.sock  # Add this for Docker monitoring

Notifications

Uptime Kuma supports 90+ notification providers. Common ones:

Telegram:

1. Create a Telegram bot via @BotFather
2. Get the bot token and your chat ID
3. Settings → Notifications → Add → Telegram

Slack:

1. Create an incoming webhook in Slack
2. Add notification with webhook URL

Email (SMTP):

• Settings → Notifications → Email
• Enter SMTP server settings

Ntfy.sh (self-hosted push notifications):

Notification type: ntfy
Server URL: https://ntfy.sh (or your self-hosted instance)
Topic: your-private-topic-name

After creating a notification, assign it to monitors: edit a monitor → Notifications → select channels.

Status Pages

Status pages are public or private pages showing service health. Useful for:

• Internal team visibility
• External users seeing service status
• Demonstrating uptime to stakeholders

Create a status page:

1. Status Page → New Status Page
2. Enter slug (URL path): status
3. Add monitors to the page
4. Set theme (light/dark)
5. Optionally set a custom domain

The public URL becomes http://your-server:3001/status/your-slug or your custom domain.

Incidents can be posted manually with date ranges and descriptions.

Tags and Organization

With many monitors, tags help organize. Tag monitors by:

• Site (homelab, work, personal)
• Type (web, database, infrastructure)
• Environment (production, staging, dev)

Filter the dashboard by tag to see only relevant monitors.

Maintenance Windows

Schedule maintenance windows to suppress alerts during planned downtime:

Settings → Maintenance → Add Maintenance:

• Schedule: specific time or recurring
• Monitors: which monitors to silence
• Title: "Weekly maintenance window"

Maintenance windows are reflected on the status page.

API Access

Uptime Kuma has a limited REST API (experimental). More complete programmatic access is via the unofficial API client or direct database manipulation.

For basic automation, webhooks (sent by the notification system) are more practical: configure a webhook notification to POST to an n8n or Home Assistant endpoint when a service goes down.

Self-Monitoring Limitation

Uptime Kuma can't monitor itself. If the Uptime Kuma container goes down, you get no alerts.

Solutions:

1. Run a second small Uptime Kuma instance that monitors the first (on different hardware)
2. Use a free external monitoring service (Freshping, Better Stack free tier) to monitor your Uptime Kuma URL
3. Configure a cron job on the host that checks if the container is running and emails you if not

For a homelab, option 2 is simplest: add your Uptime Kuma URL to one external free monitoring service.

Resource Usage

• Idle: ~50-100MB RAM
• Active: 100-200MB RAM depending on monitor count
• CPU: Minimal

Uptime Kuma runs comfortably on any machine with 512MB available RAM. It can monitor hundreds of services without significant resource impact.

Integrating with Reverse Proxy

Put Uptime Kuma behind Nginx Proxy Manager or Caddy to get HTTPS:

Caddy:

status.yourdomain.com {
  reverse_proxy localhost:3001
}

With HTTPS, your status page is accessible externally with a proper SSL certificate. This also lets you use it for external monitoring (Uptime Kuma pinging external services from your homelab's outbound connection).

The repository is at louislam/uptime-kuma. For more advanced monitoring (metrics, graphs, alerting with complex rules), pair it with Prometheus + Grafana — Uptime Kuma for uptime/status pages, Prometheus/Grafana for metrics dashboards.