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.
Built to stay highly available under large-scale monitoring
A two-stage OpenResty + Lua router assigns each new monitor to the least-busy node based on its current monitor count and status.
When a node goes down its monitors are redistributed to healthy nodes, then restored when it recovers — without interruption.
Periodically checks each node's /api/v1/health endpoint; consecutive failures mark it down and trigger failover (30s by default).
MariaDB replaces local SQLite as shared state, supporting concurrent reads and writes across nodes.
Add or remove Uptime Kuma nodes dynamically — scale out by adding machines as your monitoring grows.
Adds the REST APIs the original lacks, to query status and trigger health checks or rebalancing programmatically.
Pin traffic to a specific node with a cookie for debugging; the pin clears automatically when that node goes offline.
docker-compose-cluster.yaml brings up OpenResty, multiple nodes and MariaDB in a single command.
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 |
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
Clone https://github.com/markku636/uptime-kuma-cluster and enter the project directory.
Run the Docker Compose command below to bring up OpenResty, three Uptime Kuma nodes and MariaDB at once.
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.
Free, open source (MIT) and self-hostable. See the full docs, Docker Compose and source on GitHub.