Network Redundancy
Goal
Ensure Uptime Kuma is available 24/7, with automatic failover if the main VM goes down, using a shared database and a virtual IP.
Architecture
- Two VMs (Master / Backup) running Debian + Docker.
- Shared network storage (Windows SMB) where Uptime Kuma stores its SQLite database.
- Keepalived manages a Virtual IP (VIP) that clients use to access the service.
Images
Active / Passive Setup
| VM | Role | Status |
|---|---|---|
| VM1 | MASTER | Runs container, holds VIP, writes to shared DB |
| VM2 | BACKUP | Container stopped, monitors VIP, ready to take over |
Only one instance writes to SQLite at a time to prevent corruption.
Failover recovery time is ~5 seconds. MASTER is configured with preemption to automatically reclaim VIP and resume container operation when it comes back online.
Failover Workflow
- MASTER VM runs Uptime Kuma container, forwarding all traffic via VIP.
- BACKUP VM monitors VIP via Keepalived.
- If MASTER fails:
- VIP moves to BACKUP VM.
- Keepalived triggers a script to start Docker container on BACKUP.
- When MASTER returns:
- VIP preempts BACKUP.
- MASTER starts container; BACKUP stops container.
Images
Components
- Uptime Kuma – Docker container monitoring service.
- Docker volumes – points to shared storage.
- Keepalived – Manages VIP and triggers container start/stop scripts.
- Notify script – Starts container on MASTER, stops on BACKUP.
Benefits
- High availability: service remains reachable even if one VM fails.
- Single source of truth for monitors (shared SQLite DB) – backed up locally.
- Minimal downtime with automatic failover (~5 seconds).