Stop Guessing When Servers Crash: Uptime Kuma Dashboard Setup

There is nothing more frustrating than opening your favorite self-hosted web app, whether that is Plex, your password vault, Pi-hole, or Nextcloud, only to see a generic browser timeout error. Even worse is realizing the service has been down for twelve hours, and you had no idea because you were not actively checking it.

Commercial uptime monitoring services like Better Stack, Pingdom, or UptimeRobot offer free tiers, but they are often limited to checking every 5 or 10 minutes, restrict you to a handful of monitors, and can't check internal IP addresses behind your local firewall without complex agents.

The solution is Uptime Kuma. It is a self-hosted monitoring tool with a gorgeous modern UI, support for dozens of notification channels, customizable check intervals down to 20 seconds, and zero subscription costs.

In this guide, I will show you how to build a dedicated Uptime Kuma instance on an Ubuntu server (or inside a Proxmox LXC container) using Node.js and PM2, configure your first service monitors, and set up instant alert routing.

flowchart TD
    subgraph Engine ["Uptime Kuma Server (PM2 / LXC :3001)"]
        Scheduler["Polling Scheduler\n(20s - 60s Interval)"]
        HistoryDB[("kuma.db\nSQLite Heartbeats")]
    end

    subgraph Targets ["Monitored Homelab Infrastructure"]
        Target1["Proxmox VE Cluster\n(ICMP Ping Probe)"]
        Target2["Nextcloud Server\n(HTTP Status 200 + SSL Expiry)"]
        Target3["Pi-hole DNS\n(DNS Resolution Query :53)"]
        Target4["External Gateway\n(TCP Port 443 Check)"]
    end

    Scheduler -->|Ping| Target1
    Scheduler -->|HTTP GET| Target2
    Scheduler -->|DNS Query| Target3
    Scheduler -->|TCP Connect| Target4

    Target1 -.->|Healthy Heartbeat| HistoryDB
    Target2 -.->|Healthy Heartbeat| HistoryDB
    Target3 -.->|Healthy Heartbeat| HistoryDB
    Target4 -.->|Healthy Heartbeat| HistoryDB

    Target2 --x|Probe Failed (3 Retries)| AlertEngine{"Incident Trigger\nCriteria Met?"}
    AlertEngine -->|Dispatch Webhook| Gotify["Gotify Server\n(Priority 8 Push Alert)"]
    AlertEngine -->|Emergency Webhook| Discord["Discord / Telegram\nChannel Alert"]

    classDef kuma fill:#0f111a,stroke:#8b5cf6,stroke-width:2px,color:#f8fafc;
    classDef target fill:#1f2336,stroke:#06b6d4,stroke-width:2px,color:#f8fafc;
    class Engine,Scheduler,HistoryDB,AlertEngine kuma;
    class Targets,Target1,Target2,Target3,Target4,Gotify,Discord target;
            

Why Run Uptime Kuma via Node.js and PM2?

While many guides recommend running Uptime Kuma in Docker, installing it directly on an Ubuntu LXC or VM with Node.js and PM2 offers distinct advantages for a dedicated monitoring appliance:

• Minimal Footprint: Running natively avoids Docker daemon overhead, keeping RAM consumption under 100 MB.
• Rock-Solid Process Management: PM2 automatically restarts Uptime Kuma if the process ever crashes, logs crashes to disk, and boots the service immediately on system startup.
• Direct Network Access: Bare-metal or LXC execution means easy ICMP ping tests without having to deal with Docker bridge container permissions.

Commands to Build Uptime Kuma in Ubuntu

Here is the complete command block to update your system, install Node.js 20, clone Uptime Kuma, build it, and configure PM2 for automatic system startup.

apt update && apt upgrade -y
apt install -y curl git build-essential
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
npm install -g pm2
git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma
cd /opt/uptime-kuma
npm run setup
pm2 start server/server.js --name uptime-kuma
pm2 save
pm2 startup

Breaking Down What Each Command Does:

1. apt update && apt upgrade -y: Refreshes your Ubuntu package repositories and patches existing packages to the latest versions.
2. apt install -y curl git build-essential: Installs required utilities: curl for fetching web scripts, git for cloning the repository, and build-essential (including gcc and make) to compile SQLite dependencies.
3. curl -fsSL https://deb.nodesource.com/setup_20.x | bash -: Adds the official NodeSource repository for Node.js LTS (v20.x), ensuring you are on a modern, supported runtime.
4. apt install -y nodejs: Installs Node.js along with npm.
5. npm install -g pm2: Installs PM2 (Process Manager 2) globally on the system to keep Uptime Kuma alive in the background.
6. git clone https://github.com/louislam/uptime-kuma.git /opt/uptime-kuma: Clones the official Uptime Kuma repository into the standard /opt software directory.
7. cd /opt/uptime-kuma && npm run setup: Moves into the project directory and installs all frontend and backend dependencies, compiling the production web assets.
8. pm2 start server/server.js --name uptime-kuma: Launches the main server script under the managed name uptime-kuma.
9. pm2 save: Saves the currently running process list so PM2 knows what to restore after a reboot.
10. pm2 startup: Generates the necessary systemd service script so Uptime Kuma launches automatically whenever your server boots. (Be sure to copy and run the system command PM2 outputs at the end of this step).

First Login and Administrative Setup

Once PM2 confirms that the service is online, open your web browser and navigate to:

http://YOUR-SERVER-IP:3001

You will be greeted by the initial setup wizard:

1. Create an administrative username and a secure password.
2. Click Create to initialize your local database.

You are now looking at the clean, dark-mode-ready Uptime Kuma dashboard. On the left is your monitor list, and on the right is your real-time response time graph and status overview.

Adding Your First Service Monitor

Click the purple Add New Monitor button in the top-left corner. Uptime Kuma supports several monitor types. Here are the most useful ones for a home lab:

1. HTTP(s) Monitor (Web Apps & Dashboards)

Use this for web apps like Nextcloud, Jellyfin, Pi-hole, or your home router dashboard.

• Monitor Type: HTTP(s)
• Friendly Name: Home Pi-hole
• URL: http://192.168.1.5/admin
• Heartbeat Interval: 60 (checks every 60 seconds)
• Retries: 2 (waits for 2 consecutive failures before declaring the server down, preventing false alarms from brief network blips)

2. Ping Monitor (Routers, Switches & Physical Nodes)

If a device does not run a web server (such as a managed network switch, a Wi-Fi access point, or a smart TV), set the monitor type to Ping and enter its local IP address. Uptime Kuma will send ICMP pings and graph round-trip latency.

3. Port Monitor (Databases & Non-HTTP Services)

Want to monitor a PostgreSQL database, an SSH port, or an MQTT broker? Use the TCP Port monitor type, specify the hostname or IP, and enter the port (e.g., 5432 for Postgres or 1883 for MQTT).

Connecting Notification Channels

A dashboard is useless if you have to sit there staring at it. Uptime Kuma shines when it comes to notification integrations.

1. Click Settings in the top right menu.
2. Go to the Notifications tab.
3. Click Setup Notification.

You will see support for over 90 notification providers, including:

• Gotify: Enter your Gotify server URL and Application Token for private, self-hosted push notifications.
• Discord: Paste a Discord Webhook URL to have alerts posted into an IT or Home Lab channel.
• Telegram: Enter your Telegram Bot Token and Chat ID for instant messaging alerts.
• Ntfy: Push alerts to your phone using open-source Ntfy topics.
• Email (SMTP): Traditional email delivery via your home lab mail relay.

Check the box that says Default enabled so that all current and future monitors automatically route alerts through this channel. Click Test to verify delivery, then click Save.

Creating a Public Status Page

If other people in your household or team rely on your servers, give them a public status page so they don't have to message you asking if the internet or media server is down.

1. Click on Status Pages in the top header.
2. Click New Status Page.
3. Give it a title (e.g., Smith Family Homelab Status) and pick a slug (e.g., /status/services).
4. Drag and drop the monitors you want to show publicly (you can hide sensitive internal services).
5. Optionally add a custom logo, description text, or incident announcements.
6. Click Save.

You can now expose this status page through a Cloudflare Tunnel or local reverse proxy, giving everyone a clear, real-time look at service uptime.

Troubleshooting & Common Pitfalls

If you encounter problems during setup, check these two areas:

• Ping Monitors Failing in Docker: If you do decide to run Uptime Kuma in Docker (instead of PM2), remember that the container's user needs root permissions to send ICMP pings. If your pings fail instantly, it's a permissions issue, which is exactly why I recommend the PM2 LXC route in this guide.
• Database Corruption: Do not just yank power from the server running Uptime Kuma. The SQLite database (kuma.db) is active almost constantly. Always shut down cleanly to prevent database corruption.

Alternative: Docker Compose Stack with Gotify Alerts

If your infrastructure standardizes on containerized stacks, here is a production-ready docker-compose.yml file with persistent volume mapping and restart policies:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: always
    volumes:
      - /opt/uptime-kuma-data:/app/data
    ports:
      - "3001:3001"
    security_opt:
      - no-new-privileges:true
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

To verify Gotify alert integration directly from the server CLI before configuring Kuma:

# Test webhook delivery to Gotify notification server
curl -X POST "https://push.yourdomain.com/message?token=YOUR_APP_TOKEN" \
  -F "title=Homelab Health Alert" \
  -F "message=Uptime Kuma monitoring probe verified." \
  -F "priority=7"

Final Thoughts

Setting up Uptime Kuma turns your home lab from an unpredictable guessing game into a reliable, professional environment. By running it on Ubuntu with PM2 and pairing it with instant push notifications, you will always be the first to know when something breaks, and exactly when it comes back online.

Pair this monitoring dashboard with our Gotify Push Notifications Guide and Budget Proxmox Cluster Tour to build a self-healing private cloud.