Install Uptime Kuma on Raspberry Pi

Why Raspberry Pi for Uptime Kuma?

A Raspberry Pi running Uptime Kuma gives you a dedicated, always-on monitoring station for your entire network. It draws about 3 watts, runs silently, and Uptime Kuma’s ARM64 Docker image works natively on Pi 3B+ and newer. With a small UPS (battery backup), your monitoring stays up even during power outages — which is exactly when you want to know what went down. This guide covers the Pi-specific deployment, SD card storage considerations, and how to make your monitoring setup as reliable as possible.

Prerequisites

• Raspberry Pi 3B+, Pi 4, Pi 5, or Pi Zero 2 W
• Raspberry Pi OS Lite (64-bit / ARM64)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM
• 500 MB of free disk space
• SSH access enabled
• Network connection (wired Ethernet recommended for a monitoring device)

Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in, then verify:

docker run --rm hello-world
uname -m   # Should output: aarch64

Docker Compose Configuration

Create the project directory:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

Create docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.2.1
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - uptime-kuma-data:/app/data
      # Docker socket for container monitoring (if running other containers)
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "3001:3001"
    environment:
      - DATA_DIR=/app/data
    healthcheck:
      test: ["CMD-SHELL", "node -e \"const http = require('http'); const options = { hostname: '127.0.0.1', port: 3001, path: '/api/health', timeout: 2000 }; const req = http.request(options, (res) => { process.exit(res.statusCode === 200 ? 0 : 1); }); req.on('error', () => process.exit(1)); req.end();\""]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 30s

volumes:
  uptime-kuma-data:

Start it:

docker compose up -d

Verify:

docker compose ps
curl -s http://localhost:3001/api/health

First-Time Setup

1. Open http://your-pi-ip:3001 in a browser
2. Create your admin account
3. Add your first monitor: click Add New Monitor, select HTTP(s), enter a URL, set a 60-second heartbeat interval

What to Monitor from Your Pi

A Pi on your local network is the perfect vantage point for monitoring:

• Other self-hosted services: HTTP checks on Vaultwarden, Nextcloud, Jellyfin, etc.
• Network infrastructure: Ping checks on your router, switch, and access points
• External services: HTTP checks on your ISP’s DNS, external websites you depend on
• Docker containers: Container status via the Docker socket (if running other containers on the Pi)
• DNS resolution: DNS monitors to verify your Pi-hole or AdGuard Home is resolving correctly

Storage Considerations

SD card storage is acceptable for Uptime Kuma. Unlike a database-heavy app, Uptime Kuma’s write pattern is lightweight — it appends monitoring data to SQLite periodically. A good-quality SD card (Samsung EVO or SanDisk Extreme) will last years under this workload.

That said, limit history retention to reduce writes:

1. Go to Settings > General
2. Set Keep monitor history for: 90 days (adjust based on your needs)

If you are running other write-heavy containers on the same Pi, consider moving Docker’s data directory to a USB SSD:

sudo systemctl stop docker
sudo mkdir -p /mnt/ssd/docker
sudo rsync -a /var/lib/docker/ /mnt/ssd/docker/

Add to /etc/docker/daemon.json:

{
  "data-root": "/mnt/ssd/docker"
}

sudo systemctl start docker

UPS and Power Reliability

A monitoring system that goes down during a power outage is useless — that is exactly when you want alerts. Options:

USB UPS for Pi (recommended). A UPS HAT or inline USB UPS keeps the Pi running for 15-60 minutes during outages. Popular options:

• PiSugar S Plus (~$30, 5000mAh, ~3 hours of runtime)
• Geekworm UPS HAT (~$25, 18650 battery, ~1 hour)
• Any USB power bank with pass-through charging works as a basic UPS

Network switch on UPS. If your switch loses power, the Pi stays up but cannot reach anything. Put your core network gear on a small UPS as well.

Notification during outage. If your internet goes down with the power, local notifications (Gotify, ntfy on LAN) still work but external ones (email, Discord, Telegram) do not. Configure a local notification channel as backup.

Raspberry Pi Optimization

Use wired Ethernet. WiFi adds latency jitter to ping monitors and can drop during high load. Plug in an Ethernet cable for a monitoring device.

Reduce heartbeat interval. On a Pi, checking 50 monitors every 30 seconds is fine. Checking 200 monitors every 10 seconds will cause CPU spikes. Start with 60-second intervals and decrease if your Pi handles it well.

Docker log rotation. Add to /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "5m",
    "max-file": "2"
  }
}

Enable hardware watchdog. Auto-reboot on Pi freeze:

sudo apt install -y watchdog
sudo systemctl enable watchdog

Add to /etc/watchdog.conf:

watchdog-device = /dev/watchdog
max-load-1 = 24

Troubleshooting

Uptime Kuma shows false downtime for local services

The Pi’s network interface might be slow to come up after a reboot, causing monitors to report brief outages. Add a startup delay:

In docker-compose.yml, add:

    deploy:
      restart_policy:
        delay: 30s

Or increase the start_period in the healthcheck to give the network time to stabilize.

High CPU usage on Pi Zero 2 W

Uptime Kuma’s web UI renders charts client-side, so the Pi’s CPU is not the bottleneck when viewing the dashboard. However, if you have 100+ monitors with short intervals, the monitoring loop itself can consume significant CPU on a Zero 2 W. Increase heartbeat intervals to 120 seconds.

SQLite database locked

This happens if two processes try to write simultaneously (rare with Uptime Kuma). If you see this error in logs:

docker compose logs uptime-kuma | grep "database is locked"

Restart the container:

docker compose restart uptime-kuma

Container pulls wrong architecture

Force the correct platform if Docker defaults to the wrong one:

    platform: linux/arm64

Notifications delayed or missing

Check the notification test button in the Uptime Kuma UI. If tests work but real alerts are delayed, your heartbeat interval may be too long. A 60-second interval means worst case you detect an outage after 60 seconds plus retry time.

Resource Requirements

• RAM: ~80 MB idle with a few monitors, ~150 MB with 50+ monitors
• CPU: Low on Pi 4/5. Moderate on Pi Zero 2 W with many monitors.
• Disk: ~50 MB for the application, SQLite grows slowly (~100 MB after months of monitoring)
• Power: Adds essentially nothing to Pi baseline (~3W total)

Related

• How to Self-Host Uptime Kuma with Docker
• Install Uptime Kuma on Ubuntu Server
• Install Uptime Kuma on Proxmox VE
• Best Self-Hosted Monitoring Tools
• Docker Compose Basics
• Reverse Proxy Explained