Setting Up Cluster Uptime on a Raspberry Pi: The Ultimate HomeLab Guide

One of the most satisfying projects for any HomeLab enthusiast is building your own monitoring station. There is something visceral about having a physical device on your desk that glows green when the internet is up and red when it’s down.

The Raspberry Pi (especially the Pi 4 or the new Pi 5) is the perfect candidate for this. It’s low power, silent, and powerful enough to run a full monitoring stack.

In this guide, we will turn a fresh Raspberry Pi into a dedicated Cluster Uptime instance that can monitor your Plex server, Home Assistant, Pi-hole, and external websites.

Prerequisities

• Hardware: Raspberry Pi 4 (2GB+ RAM recommended) or Pi 5.
• OS: Raspberry Pi OS Lite (64-bit) is preferred for headless setups.
• Network: Ethernet connection is preferred over Wi-Fi for stability.

Step 1: Preparing the Environment

First, ssh into your Pi. We always start by updating the packages to ensure we have the latest security patches.

ssh [email protected]
sudo apt update && sudo apt upgrade -y

Install Docker

We will use Docker to keep our system clean. The official convenience script is the easiest way to install it on a Pi.

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

Logout and log back in for the group changes to take effect.

Step 2: Deploying Cluster Uptime

We provide multi-arch Docker images, meaning the exact same image tag works on amd64 (Intel/AMD) and arm64 (Raspberry Pi/M1 Mac).

Create a directory for your monitoring stack:

mkdir ~/uptime-monitor
cd ~/uptime-monitor

Create a docker-compose.yml file:

version: '3.8'

services:
  clusteruptime:
    image: clusteruptime/clusteruptime:latest
    container_name: uptime-core
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - DATA_DIR=/app/data
      - DISABLE_TELEMETRY=true # Optional: Privacy focus

Start the stack:

docker compose up -d

Step 3: Configuration and Usage

Navigate to http://raspberrypi.local:3000 in your browser. You should see the Cluster Uptime welcome screen.

Best Practices for SD Card Life

Raspberry Pis run on SD cards, which have limited write cycles. A monitoring tool writing logs every second can kill an SD card in a few months.

• Recommendation: If checking frequently, mount an external USB SSD or a USB stick for the ./data volume.

Step 4: Monitoring Your HomeLab

Now, let’s add some local monitors. Since the Pi is inside your network, it can see things the outside internet can’t.

1. Pi-hole: http://192.168.1.5/admin
2. Plex: http://192.168.1.10:32400/web
3. Router Gateway: http://192.168.1.1 (Check for simple Ping)

Step 5: The “Physical” Status Light (Advanced)

Since we are on a Pi, let’s use the GPIO pins! You can wire a simple LED to GPIO Pin 18.

Here is a simple Python script (using libraries usually available on Pi) to sync the LED with your status:

import RPi.GPIO as GPIO
import time
import requests

GPIO.setmode(GPIO.BCM)
GPIO.setup(18, GPIO.OUT)

while True:
    try:
        # Check Cluster Uptime API
        r = requests.get('http://localhost:3000/api/status')
        status = r.json()['status']

        if status == 'up':
            GPIO.output(18, GPIO.HIGH) # Green Light On
        else:
            GPIO.output(18, GPIO.LOW)  # Light Off (or Red)
    except:
        pass
    time.sleep(10)

Now you have a physical monitoring appliance for under $50.