Overview
Runs Uptime Kuma, a monitoring tool that checks websites, ports, DNS and more, keeps their history, sends notifications and publishes status pages. The block is a singleton that runs where its volume's primary is, behind a VIP. The volume holds Uptime Kuma's SQLite database (monitors, heartbeat history, users, notifications, status pages), its uploaded images and db-config.json.
Open http://<VIP>/ right after deploying: until the first account is created, anyone who reaches Uptime Kuma can create it.
- Shape
- Singleton on a replicated volume
- Reached at
- VIP on HTTP
- Node package
pkgs.uptime-kuma
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.uptime-kuma, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: uptime namespace: default spec: type: monitor/uptime-kuma replicas: 1 strategy: kind: SINGLETON resources: requests: cpu: 250m memory: 256Mi storage: - name: uptime-kuma-data size: 2Gi replication: 3 mountPath: /var/lib/uptime-kuma network: ports: - name: http port: 80 target_port: 3001 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 3001 period_seconds: 2
$ expanse ctl block apply -f uptime-kuma.yaml --dry-run # validate only $ expanse ctl block apply -f uptime-kuma.yaml
Configuration
Everything else (monitors, notifications, status pages, users) is set in Uptime Kuma's web UI and kept on the volume. The block always uses SQLite, so the first-run page that asks for a database never shows.
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
port | 3001 | Uptime Kuma's HTTP port, the target_port of 80. |
Using it
Point a name at the block's VIP (expanse ctl block get uptime) and sign in. For HTTPS, put a web/caddy block in front.
Monitors run from whichever node serves the block, so every node must be able to reach what is monitored. Heartbeat history grows with the number of monitors and how long it is kept (Settings → Monitor History); size the volume for it. To watch the cluster's own nodes and blocks, monitor/prometheus and monitor/grafana fit better; Uptime Kuma suits checking that services answer.
When a node fails
When the serving node dies, the block, its volume's primary and its VIP move together to a survivor, and Uptime Kuma starts there on the same volume. Checks pause until it is back; the address stays the same, and browsers stay signed in, because the key that signs their sessions is in the database.
Nothing Uptime Kuma acknowledged is lost. Uptime Kuma has no setting for SQLite's sync level, so the block starts it with a small preload that makes every commit sync, and logs expanse: SQLite synchronous pragmas forced to FULL. Uploaded images and db-config.json are flushed every 2 seconds. In Expanse's three-node VM test, a survivor took over 72 seconds after the crash and Uptime Kuma answered at 106 seconds with all 21 monitors created before it.
Limits
- One Uptime Kuma at a time: it keeps its state in SQLite on one volume.
- No MariaDB database: the block always uses SQLite on its volume.
- No Real Browser monitors: nodes do not ship Chromium.
- No HTTPS inside the block; use
web/caddyin front. - Backups are separate: back up the volume with
util/restic-backup.
Source
- docs/UPTIME-KUMA.md: the Expanse guide this page follows.
- nix/blocks/monitor/uptime-kuma: the type's identity and JSON Schema.