When self-hosting home lab services, media servers, and network storage, outages are inevitable: a router reboot alters an IP address, a Docker container runs out of disk space, or an external API changes. Discovering that your smart home hub or password vault crashed only when your family complains is frustrating.

While commercial website monitoring services exist, they only monitor public-facing internet domains. They cannot check internal home network services like your Pi-hole DNS resolver, local Samba NAS, or private Home Assistant dashboard.

Uptime Kuma is the ultimate self-hosted uptime monitoring tool. Built with an intuitive, responsive interface, it lets you monitor all your home lab services across internal LAN and public internet connections. It supports HTTP(s), Ping (ICMP), TCP Port checks, DNS lookups, and passive Push/Heartbeat monitors, delivering instant notifications via Telegram, Discord, Email, Webhooks, or push notifications the moment an outage occurs.

This guide walks you through deploying Uptime Kuma on Raspberry Pi using Docker Compose, configuring essential monitor types, setting up instant alert channels, creating a public status page, and monitoring your server with Open Pi.

Hardware planning and prerequisites

  • Supported Boards: Uptime Kuma is efficient and lightweight. A Raspberry Pi 3, 4, 5, or Zero 2 W with at least 1 GB of RAM is ideal.
  • Network Interface: A wired gigabit Ethernet connection ensures network latency tests (Ping) reflect true service health rather than local Wi-Fi fluctuations.
  • Storage: An A2-rated microSD card or USB 3.0 SSD. Uptime Kuma records response times and incident history in an embedded SQLite database.

Deploy Uptime Kuma with Docker Compose

Deploying Uptime Kuma via Docker Compose keeps the application and its Node.js environment cleanly isolated.

Create a project directory:

BASH
mkdir -p "$HOME/uptime-kuma/data"
cd "$HOME/uptime-kuma"

Create a compose.yaml file:

YAML
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=UTC

Launch the container:

BASH
docker compose up -d
docker compose logs -f

Open http://<YOUR_PI_IP>:3001 in your browser.

Initial onboarding and account creation

When you open port 3001 for the first time: 1. Select your preferred display language. 2. Create your primary administrator username and a strong password. 3. You are immediately presented with the clean, dark-mode Uptime Kuma dashboard.

Configuring essential monitor types

Click Add New Monitor in the top navigation bar. Uptime Kuma supports a variety of monitoring strategies:

1. HTTP(s) Web Application Monitor

Monitors web dashboards like Vaultwarden, Home Assistant, or Jellyfin: - Monitor Type: HTTP(s) - Friendly Name: Home Assistant - URL: http://192.168.1.60:8123 - Heartbeat Interval: 60 seconds - Accepted Status Codes: 200-299 - Uptime Kuma alerts you if the HTTP response code indicates an error (e.g. 500, 502, or 404).

2. Ping (ICMP) Network Device Monitor

Monitors physical hardware availability (routers, network switches, printers, or smart TVs): - Monitor Type: Ping - Friendly Name: Core Router Gateway - Hostname: 192.168.1.1 - Uptime Kuma tracks packet round-trip time (ping latency in milliseconds) and alerts you if packet loss exceeds thresholds.

3. TCP Port Check

Monitors background network daemons that do not serve HTTP web pages: - Monitor Type: Port - Friendly Name: Mosquitto MQTT Broker - Hostname: 192.168.1.50 - Port: 1883

4. Push / Heartbeat Monitor (For Cron Jobs & Backups)

What happens if an automated nightly backup script fails silently? A Push Monitor reverses the monitoring flow: - Create a monitor of type Push. - Uptime Kuma generates a unique webhook URL (e.g., http://192.168.1.50:3001/api/push/abc123xyz?status=up&msg=OK). - Add a curl call to the end of your automated backup script: bash curl -s "http://192.168.1.50:3001/api/push/abc123xyz?status=up&msg=OK" - If Uptime Kuma does not receive the expected ping within the scheduled timeframe, it triggers an alert notifying you that your backup failed to run!

Setting up instant alert notifications

A monitoring dashboard is only helpful if it reaches you before users complain.

Under Settings -> Notifications -> Setup Notification, choose from dozens of integrations:

  1. Message @BotFather on Telegram to create a free notification bot and receive an API Bot Token.
  2. Start a chat with your new bot and get your Chat ID using @userinfobot.
  3. In Uptime Kuma, select Telegram, enter your Bot Token and Chat ID, and click Test.
  4. You will instantly receive a test message on your phone!

Discord / Slack Webhooks

  1. In your Discord or Slack channel settings, create an Incoming Webhook.
  2. Paste the Webhook URL into Uptime Kuma.
  3. Uptime Kuma posts formatted embed cards with red/green status badges whenever an incident begins or resolves.

Creating beautiful public or private Status Pages

Keep your family or colleagues informed without giving them administrator dashboard access:

  1. Click Status Pages in the top navigation bar.
  2. Name your status page (e.g., Home Services Status).
  3. Drag and drop your monitors into organized groups (Networking, Smart Home, Media Storage).
  4. Customize the logo, theme color, and description.
  5. Anyone visiting /status/home can check the live operational status and incident history of your home lab.

Monitor Uptime Kuma with Open Pi

Who monitors the monitor? Ensuring your Raspberry Pi has adequate resources to run continuous health checks is essential.

With Open Pi on your iOS or Android device: - Host Uptime & Resource Metrics: Track CPU temperatures, load averages, and memory allocation in real time. - Docker Container Health: Verify that the uptime-kuma container is running and healthy. - Port Verification: Ensure port 3001 remains accessible across your local subnet.

Troubleshooting Uptime Kuma

  • Ping (ICMP) Monitors Failing Inside Docker: Linux containers sometimes lack raw network socket capabilities required to send ICMP ping packets. In your compose.yaml, you can add cap_add: [NET_RAW] or verify that Docker has ICMP socket access.
  • Notifications Failing Behind Corporate Firewalls: Ensure the Raspberry Pi has outbound internet access to reach external notification APIs (Telegram, Discord, Pushover).
  • Database Growth: Uptime Kuma stores individual ping latency records. Under Settings -> General, configure Data Retention (e.g., retain data for 30 or 60 days) to prevent the SQLite database from growing indefinitely.

Sources and further reading

Open Pi logo
Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your home server projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi App StoreGoogle Play
About this guide

Researched and validated against official project documentation and community standards on September 11, 2026. Review your board model, storage, and current release notes before deploying.