Skip to main content

📈 Uptime Kuma — Self‑hosted Uptime Monitor (Docker)

Uptime Kuma is a lightweight self‑hosted status monitor (like "Uptime Robot") you can run on a Raspberry Pi. It monitors websites, servers and services and sends alerts when something is down.

This guide gives a clear Docker Compose example, startup/verification steps, backup/restore notes, reverse‑proxy recommendations and troubleshooting tips.

✅ Prerequisites​

  • Raspberry Pi with Docker and Docker Compose installed
  • Basic knowledge of Docker and a terminal (SSH or local)
  • Enough disk for logs and data (1–5 GB typical; more if you keep long history)

📂 Create project folder​

On the Pi run:

mkdir -p ~/docker/appdata/uptime-kuma
cd ~/docker/appdata/uptime-kuma

Create docker-compose.yml and paste:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"            # host:container (change host port if needed)
    volumes:
      - ./data:/app/data       # persistent storage for config and history
    environment:
      - TZ=Europe/Oslo         # set your timezone (optional)

Notes:

  • Using ./data keeps your configuration and history across updates.
  • If port 3001 conflicts, change the left side (e.g. "3002:3001").
  • For production or external access, run behind a reverse proxy (see below).

🚀 Start and verify​

Start the container:

docker compose up -d

Check it is running:

docker ps --filter "name=uptime-kuma"
docker logs -f uptime-kuma

Stop and remove:

docker compose down

Restart container:

docker compose restart uptime-kuma

Update to newest image:

docker compose pull uptime-kuma
docker compose up -d

🌐 Access the UI​

Open a browser to:

http://PI-IP:3001

On first run you'll create an admin account. If you use a reverse proxy with TLS, use HTTPS.

🔔 What you can monitor​

  • HTTP(S) websites (GET/HEAD checks, response codes, string matching)
  • Ping / ICMP checks (via host ping)
  • TCP port checks (e.g. SSH, SMTP)
  • Docker containers (by probing exposed ports)
  • Custom checks via webhooks or scripts

Uptime Kuma supports many notification methods (email, Telegram, Discord, Slack, Webhooks, Pushover, Gotify, ntfy, etc.).

🔒 Reverse proxy & HTTPS (recommended for remote access)​

For secure remote access, put Uptime Kuma behind a reverse proxy (nginx, Traefik) and obtain a TLS certificate (Let's Encrypt). Example proxy considerations:

  • Terminate TLS at proxy, forward to container on 127.0.0.1:3001 or internal network.
  • Protect the admin interface with login, and optionally restrict access by IP or add basic auth at the proxy.

If using host networking or exposing port 3001 directly, ensure firewall rules and authentication are in place.

💾 Backup & migrate​

To backup Uptime Kuma data:

tar czf uptime-kuma-backup-$(date +%F).tar.gz ./data
# or copy the folder to another host

To restore:

  1. Stop container: docker compose down
  2. Extract backup into ./data
  3. Start container: docker compose up -d

When migrating to another host, copy the data directory and use the same image tag.

⚙️ Tips & recommended settings​

  • Limit history retention in the app settings if disk is constrained.
  • If monitoring many targets, consider a Pi with more CPU/RAM.
  • Use Docker healthchecks or external monitoring of the Uptime Kuma container itself.
  • Persist logs elsewhere if you need long term audit trails.

🛠 Troubleshooting​

  • UI not reachable:

    • Confirm container is running: docker ps
    • Confirm port mapping: ss -tulpn | grep 3001
    • Check logs: docker logs uptime-kuma

  • Data not persisted after restart:

    • Ensure ./data exists and is writable by Docker host user.
    • Inspect container mounts: docker inspect uptime-kuma --format '{{json .Mounts}}'

  • Notifications failing:

    • Verify notification service credentials and test from Uptime Kuma UI.
    • Check outbound network access from the Pi/container.

Example quick commands​

# start
docker compose up -d

# logs
docker logs -f uptime-kuma

# update
docker compose pull uptime-kuma
docker compose up -d

# backup
tar czf uptime-kuma-backup-$(date +%F).tar.gz ./data

Uptime Kuma is now ready to monitor your services. Keep data backed up, secure the UI for remote access, and adjust polling frequency and history to fit your Raspberry Pi's resources.