How to Install Uptime Kuma on Raspberry Pi to Monitor Your Services

Uptime Kuma is a self-hosted monitoring tool that lets you keep an eye on your websites, APIs, and network services. It features a clean, modern dashboard and supports multiple notification channels. Running it on a Raspberry Pi gives you a dedicated, low-power monitoring station for your entire homelab.

What is Uptime Kuma?

Uptime Kuma is an open-source, self-hosted uptime monitor similar to services like UptimeRobot, but entirely under your control. It supports:

HTTP(S), TCP, Ping, DNS, and other monitor types
Notifications via email, Discord, Telegram, Slack, and many more
Public status pages you can share with others
Response time charts and uptime history
Multi-language support

Prerequisites

Before you begin, make sure you have:

A Raspberry Pi (3B+ or newer) running Raspberry Pi OS
Docker and Docker Compose installed
A static IP address assigned to your Pi

If you need help with Docker, check out our Docker installation guide.

Setting Up Uptime Kuma with Docker Compose

Create a directory for your Uptime Kuma configuration:

Bash

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

Create the docker-compose.yml file:

Bash

nano docker-compose.yml

Paste the following configuration:

YAML

version: "3"

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

Start the container:

Bash

docker-compose up -d

Once the container is running, open your browser and navigate to http://<your-pi-ip>:3001. You will be prompted to create an admin account on first launch.

Adding Monitors

After logging in, click the "Add New Monitor" button. Uptime Kuma supports several monitor types.

HTTP(S) Monitor

Use this to monitor websites and APIs. Set the monitor type to HTTP(s), enter the URL you want to monitor, and choose a check interval (the default is 60 seconds). Uptime Kuma will track response time and status codes.

TCP Monitor

TCP monitors are useful for checking if a specific port is open and responding on a host. Set the monitor type to TCP, enter the hostname and port number. This is great for monitoring services like databases or game servers.

Ping Monitor

Ping monitors send ICMP packets to check if a host is reachable. Set the monitor type to Ping and enter the hostname or IP address. This is ideal for monitoring network devices like routers and switches.

Setting Up Notifications

Uptime Kuma supports over 90 notification services. Navigate to Settings then Notifications to configure them.

Email Notifications

Click "Setup Notification" and select SMTP. Enter your mail server details:

SMTP Host: Your mail server address (e.g., smtp.gmail.com)
SMTP Port: Usually 587 for TLS
Username and Password: Your email credentials
From/To Email: The sender and recipient addresses

Discord Notifications

Select Discord as the notification type. You will need a Discord Webhook URL. In your Discord server, go to Server Settings, then Integrations, then Webhooks, create a new webhook, and copy the URL.

Telegram Notifications

Select Telegram as the notification type. You will need a Bot Token from @BotFather and your Chat ID. Send /newbot to @BotFather on Telegram to create a bot and receive your token.

Creating Status Pages

One of Uptime Kuma's best features is public status pages. Navigate to Status Pages in the top menu and click "New Status Page". Give it a name and slug, then add the monitors you want to display. You can share the resulting URL with your users or team so they can check service status without needing login access.

Status pages are accessible at http://<your-pi-ip>:3001/status/<your-slug>.

Updating Uptime Kuma

To update to the latest version, run:

Bash

cd ~/uptime-kuma
docker-compose pull
docker-compose down
docker-compose up -d

Your data is persisted in the ./data volume, so updates will not affect your configuration or history.

Troubleshooting

Container won't start: Check logs with docker logs uptime-kuma for error messages.
Cannot access the dashboard: Verify port 3001 is not blocked by a firewall. Run sudo ufw allow 3001 if UFW is active.
Notifications not sending: Test the notification from the setup screen using the "Test" button. Double-check credentials and webhook URLs.
High memory usage: Uptime Kuma stores history in a SQLite database. If the database grows too large, consider reducing the monitor retention period in Settings.
DNS resolution failures inside the container: Ensure your Pi has working DNS. You can add dns: [8.8.8.8] under the service in your compose file if needed.

Conclusion

Uptime Kuma is a lightweight yet powerful monitoring solution that runs perfectly on a Raspberry Pi. With support for multiple monitor types, dozens of notification channels, and public status pages, it gives you everything you need to keep tabs on your services without relying on third-party platforms.