Back to articles
AI & Cloud

Building an Uptime Kuma Cluster: Mutual Monitoring Solution Between VPS for Enterprises

A detailed guide to building an Uptime Kuma cluster for mutual monitoring between VPS servers, ensuring high reliability and fast alerts for businesses.

DPTCloud Engineering4 min read
Building an Uptime Kuma Cluster: Mutual Monitoring Solution Between VPS for Enterprises

Image credit: wikimedia

Building an Uptime Kuma Cluster for Mutual Monitoring Between VPS

Uptime Kuma is an open-source, self-hosted monitoring tool that tracks the status of services, websites, and servers. With a cluster architecture, Uptime Kuma can monitor each other across multiple VPS instances, enabling enterprises to detect failures quickly and maintain system stability. This guide walks you through building an effective Uptime Kuma cluster.

Prerequisites Before Starting

To deploy an Uptime Kuma cluster, you need:

  • At least 2 VPS (Virtual Private Servers) with stable internet connectivity.
  • Ensure VPS instances can communicate over the network (typically port 3001 or a custom port).
  • SSH access to each VPS for installation and configuration.
  • Docker and Docker Compose installed on each VPS.

Install Uptime Kuma on Each VPS

On each VPS, perform the following steps to install Uptime Kuma:

# Create directory for Uptime Kuma mkdir -p ~/uptime-kuma && cd ~/uptime-kuma # Create docker-compose.yml file cat > docker-compose.yml << EOF version: '3.8' services: uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma ports: - "3001:3001" volumes: - ./data:/app/data restart: unless-stopped EOF # Start Uptime Kuma docker-compose up -d

Run the commands on each VPS. After startup, access Uptime Kuma via a browser at http://:3001.

Configure Uptime Kuma Cluster

To form a cluster, designate one VPS as the master and the others as workers. For example: VPS 1 as master, VPS 2 as worker.

  1. On the master VPS (VPS 1), access the Uptime Kuma interface and go to Settings → Cluster.
  2. Enable Cluster and enter the worker VPS (VPS 2) details:
    • Cluster Node IP: 192.168.1.2 (IP of VPS 2)
    • Cluster Node Port: 3001
    • Cluster Node Name: worker-2
  3. Click Save and restart the service.
  4. On the worker VPS (VPS 2), repeat the process but select Join Cluster and enter the master (VPS 1) details.

After configuration, Uptime Kuma will automatically synchronize status across nodes. If one VPS fails, the system alerts immediately.

Verification and Testing

To verify cluster stability, run these commands:

# Check service status on each VPS docker-compose ps # Check Uptime Kuma logs docker-compose logs -f uptime-kuma

Access the Uptime Kuma interface and confirm that all nodes appear in the cluster. If the status shows Online, the configuration is successful.

Troubleshooting

  • Cannot connect between VPS instances: Check firewall rules and ensure port 3001 is open.
  • Uptime Kuma not syncing: Review logs and confirm cluster configuration is accurate.
  • Cannot access the interface: Verify Docker is running and the port is not occupied.

References

For more information on Uptime Kuma and advanced features, refer to:

Practical Testing

To verify the Uptime Kuma cluster functions correctly, perform safe, non-destructive tests. Requirements: two VPS with Docker and Docker Compose installed, port 3001 open on both, and SSH access available.

# On each VPS, check service status
$ docker-compose ps
  Name             Command               State           Ports
  ---------------------------------------------------------------------
  uptime-kuma   /usr/local/bin/uptime-kuma   Up      0.0.0.0:3001->3001/tcp

# Check logs for cluster synchronization
$ docker-compose logs -f uptime-kuma
[INFO] Cluster: Joining cluster with master at 192.168.1.1:3001
[INFO] Cluster: Connected to master
[INFO] Cluster: Node registered successfully

# Check node status in web interface
# Access http://:3001, go to Settings > Cluster
# Verify all nodes show status as "Online"

To test mutual monitoring, stop the service on one VPS (e.g., docker-compose stop uptime-kuma) and observe whether the other VPS shows a "Down" status for the stopped node in the Uptime Kuma interface. If the alert appears within 1–2 minutes, the cluster is functioning properly.

Limitations: Testing cannot be performed if VPS instances lack network connectivity or are blocked by firewalls. Avoid using docker-compose down or modifying configurations during testing.

DPTCloud Tier III Infrastructure

High-RAM Cloud VPS Plans Optimized for AI, Databases & Cache

Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.

View 22 VPS Plans
ECO · vn-02Recommended

VPS-4E

297.000 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe
ECO · vn-02

VPS-5E

614.900 ₫ / mo

10% VAT included

  • CPU: 8 vCPU
  • RAM: 16 GB
  • SSD: 100 GB NVMe
ADVANCED · vn-03Recommended

VPS-4T

548.900 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe

Related Articles

View all
ZaloZalo SupportDiscord0384 753 478