Uptime Kuma Cluster
Turn single-node Uptime Kuma into a highly available cluster — smart load balancing, automatic failover and health checks, started with a single Docker Compose command.
Public Wi-Fi and travel, handled by NordVPN
One tap encrypts everything, with servers in 137 countries. 10 devices per account, 30-day money-back guarantee.
Contains affiliate links
Core Features
Built to stay highly available under large-scale monitoring
Smart load balancing
A two-stage OpenResty + Lua router assigns each new monitor to the least-busy node based on its current monitor count and status.
Automatic failover
When a node goes down its monitors are redistributed to healthy nodes, then restored when it recovers — without interruption.
Health checks
Periodically checks each node's /api/v1/health endpoint; consecutive failures mark it down and trigger failover (30s by default).
Shared database
MariaDB replaces local SQLite as shared state, supporting concurrent reads and writes across nodes.
Horizontal scaling
Add or remove Uptime Kuma nodes dynamically — scale out by adding machines as your monitoring grows.
Cluster management API
Adds the REST APIs the original lacks, to query status and trigger health checks or rebalancing programmatically.
Fixed-node debugging
Pin traffic to a specific node with a cookie for debugging; the pin clears automatically when that node goes offline.
One-command Docker
docker-compose-cluster.yaml brings up OpenResty, multiple nodes and MariaDB in a single command.
Original vs Cluster
What this project adds on top of the original Uptime Kuma
| Feature | Original Uptime Kuma | This project (Cluster) |
|---|---|---|
| Architecture | Single node | Multi-node HA cluster |
| Database | SQLite (local) | MariaDB (shared) |
| Load balancing | None | OpenResty + Lua smart routing |
| Failure handling | Service interruption | Automatic monitor redistribution |
| Horizontal scaling | Not supported | Dynamic add/remove nodes |
| Health checks | None | Periodic endpoint checks |
| Cluster management API | None | A set of REST APIs |
Cluster Management API
All prefixed with /lb for automated monitoring and management
/lb/pingLiveness check
/lb/healthCluster health status
/lb/system-statusFull system status report
/lb/available-nodesList nodes with load metrics
/lb/fixed-node/{node}Pin traffic to a specific node
/lb/trigger-health-checkManually trigger a health scan
/lb/trigger-rebalancingForce monitor redistribution
/lb/rebalancing-statusView rebalancing progress
Quick Start
- 1
Clone https://github.com/markku636/uptime-kuma-cluster and enter the project directory.
- 2
Run the Docker Compose command below to bring up OpenResty, three Uptime Kuma nodes and MariaDB at once.
- 3
Verify with curl http://localhost:8084/lb/health and /lb/available-nodes that the cluster is healthy.
Requires Docker and Docker Compose; node count, health-check interval and more are configurable via environment variables.
Need a highly available platform that handles monitoring at scale?
Free, open source (MIT) and self-hostable. See the full docs, Docker Compose and source on GitHub.
Every tool here is free and open source
No paywall, no sign-up, and the source is public on GitHub. If one of them saved you time, buy me a coffee so the updates and the next tool keep coming.
Deal
The network you code on is rarely your own
NordVPN encrypts the whole connection: café and hotel Wi-Fi stop being someone else's listening post, and while you travel your bank app, your company dashboards and the streaming services back home still work. One tap in the app, and the NordLynx protocol keeps it fast enough that you forget it is on. One account covers 10 devices, with a 30-day money-back guarantee.
- Public Wi-Fi encrypted end to end
- Servers in 137 countries, reach home services abroad
- 10 devices per account, 30-day refund
Contains affiliate links