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.
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.
RESTful API
Adds the /api/v1 REST API the original lacks: create, read, update and delete monitors, nodes, status pages and groups over HTTP, plus /lb cluster operations endpoints.
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 | /lb endpoints for status, health checks and rebalancing |
| RESTful API | None (monitor changes only via the web UI's Socket.IO) | /api/v1 CRUD + Swagger docs |
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
RESTful API (/api/v1)
The original Uptime Kuma only lets you manage monitors in the web UI. This API lets CI/CD, scripts and internal systems manage the whole cluster with plain HTTP and JSON.
/api/v1/monitorsList all monitors
/api/v1/monitorsCreate a monitor; without node_id it goes to the online node with the fewest monitors
/api/v1/monitors/{id}Get one monitor
/api/v1/monitors/{id}Update a monitor
/api/v1/monitors/{id}Delete a monitor
/api/v1/monitors/{id}/heartbeatsFetch heartbeats for a time period
/api/v1/nodesList cluster nodes (POST / PUT / DELETE also available)
/api/v1/nodes/{id}/monitorsSee which monitors a node is running
/api/v1/status-pagesList status pages (POST / PUT / DELETE by slug)
/api/v1/groupsCreate a monitor group (GET / PUT /api/v1/groups/{id} too)
/api/v1/notificationsList notification settings
/api/v1/healthNode liveness check (no auth, no rate limit)
- Auth: send Authorization: Bearer <JWT>. The server verifies the token and checks the account is still active. /api/v1/status and /api/v1/health need no login.
- Rate limit: 100 requests per IP per 15 minutes by default, then 429. Adjust with the API_RATE_LIMIT environment variable.
- Capacity: each node holds up to 1,000 active monitors. When every node is full the API returns an error instead of overloading one.
- Responses always look like { ok, msg, data }; validation failures list their reasons in errors.
- Docs: /api-docs serves Swagger UI for trying requests in the browser; /api-docs.json is the OpenAPI 3.0 spec for generating clients.
Example: create an HTTP monitor with curl
curl -X POST http://localhost:8084/api/v1/monitors \
-H "Authorization: Bearer $UPTIME_KUMA_JWT" \
-H "Content-Type: application/json" \
-d '{"name":"Website","type":"http","url":"https://example.com","interval":60}'
# 201 => {"ok":true,"msg":"Monitor created successfully","data":{"monitor_id":42,"node_id":"node2"}}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.