Uptime Kuma backup and recovery¶
The scheduled production backup captures Kuma's SQLite database and its
matching private admin credential file, alongside PostgreSQL, uploads and
runtime environment files. It uses the exact helper shipped by that workflow
run: deploy/backup-uptime-kuma.py.
The workflow ships that file and checks its committed SHA-256 on the server
before execution, so a stale or replaced helper fails the backup run.
What is captured¶
Each private full-<timestamp> backup set contains:
| File | Contents |
|---|---|
uptime-kuma.sqlite |
A completed SQLite online backup: monitors, history, notifications, settings and users |
uptime-kuma-credentials.json.bak |
The matching private admin username/password file |
uptime-kuma-db-config.json |
Minimal Kuma 2 configuration selecting SQLite |
uptime-kuma-manifest.json |
Completion status, file checksums, critical table counts, capture time and image identity/digests |
The directory must be mode 700 and all files are mode 600. The database also contains provider configuration and secrets; protect it like the original runtime configuration. These files automatically join the existing off-site mirror because it transfers the completed backup set's files. Off-site transfer and encryption still require the existing operator-managed configuration; a local Kuma snapshot does not prove that off-site recovery is available.
Capture does not stop or restart Kuma, change its volume, checkpoint the live
database, authenticate through its HTTP API, or send notifications. The pinned
Kuma image's SQLite CLI opens the source read-only and uses .backup to include
committed WAL state in one self-contained snapshot. It never archives the live
kuma.db file by itself or tries to copy a moving DB/WAL pair.
Kuma 2's actual db-config.json database type is checked; an installation
configured for MariaDB is refused even if a stale SQLite file still exists.
The helper checks the supplied admin password against the snapshot, using Kuma's own password verifier, and checks that the credential file did not change during capture. SQLite integrity, foreign keys and the user, monitor, notification, notification-assignment, setting and heartbeat table counts are verified. Recovery into a fresh disposable SQLite database is exercised before the files are published. The completion manifest is published last.
Installation states and failure handling¶
On an older installation with no Kuma container, named volume or credential
file, the manifest records status: not_installed. This receipt is an explicit
skip, not a completed Kuma backup.
If Kuma state exists, capture fails when the container is missing/stopped, credentials are missing, permissions are unsafe, the password does not match, credentials change during capture, or snapshot/verification fails. Such a run does not publish a complete manifest. The scheduled workflow fails before retention and off-site mirroring, preserving older successful sets.
A destination lock prevents competing captures from mixing their files. An interrupted process can leave a lock or partial set. Inspect that set privately and capture to a new directory; the helper never overwrites an existing snapshot, credential file or manifest. Do not delete or replace the live volume to resolve a backup failure.
Capture and offline verification¶
The normal capture is run by the daily production backup under the deployment lock. For a separately authorized manual capture, select a new private backup directory and run the committed helper on the VPS:
python3 /opt/aim-store/deploy/backup-uptime-kuma.py \
--backup-dir /path/to/new-private-backup-set
Do not paste credential JSON or database contents into chat, workflow output or command arguments. Normal output reports status and aggregate counts only.
The following check is offline and does not require Docker, the production container, account access or network connectivity:
python3 deploy/backup-uptime-kuma.py --verify /path/to/private-backup-set
It checks the file permissions and checksums, runs SQLite integrity/foreign-key checks, checks the active saved username and critical table counts, then copies the snapshot through SQLite's backup API into a fresh private temporary database and compares its recovered state. That temporary recovery database is removed. It does not alter the archived files, start Kuma, poll endpoints or send email.
The password pairing is verified during capture with Kuma's own implementation. The offline verifier then checks that the database and credential files still match that capture's manifest; it does not install a second password-hashing implementation on the host. Checksums detect accidental corruption and mixed sets. They do not authenticate a maliciously replaced manifest: retain trusted, access-controlled backup copies.
Recovering an installation¶
An actual production restore is a separate, operator-controlled maintenance operation. Verify the selected set offline before changing services.
- Keep the current Kuma state and credentials as a rollback copy. Stop only Kuma for replacement; never write a snapshot over a running SQLite database.
- Use the recorded image repository digest when available, or the recorded
Kuma version. The local image ID is comparison metadata, not a registry pull
reference. Restore into a new empty data volume, placing the saved snapshot
at
/app/data/kuma.dbwith private permissions and ownership suitable for that image. Placeuptime-kuma-db-config.jsonalongside it as/app/data/db-config.json, also private. Do not reuse a production volume for a rehearsal. - Restore
uptime-kuma-credentials.json.bakas/opt/aim-store/monitoring/.uptime-kuma-credentials.json, mode 600. Restore the monitoring runtime.envfrom the same full set using the general recovery procedure; do not print it. Keep the dashboard bound to loopback. - For a full-app rehearsal, isolate outbound networking first. The restored database contains active monitors and SMTP credentials; starting it with unrestricted networking can poll real endpoints and send notifications.
- After an authorized production start, verify the private dashboard login,
monitor history and notification assignments.
bash uptime-kuma/provision.sh --verifyandbash uptime-kuma/configure-email.sh --verify, run from the monitoring directory, are read-only checks. Do not use account setup or password-reset commands on a restored volume. Send a notification test only when the operator intentionally requests it.
Verification evidence and limits¶
Run the synthetic tests without Docker or customer data:
PYTHONDONTWRITEBYTECODE=1 python3 deploy/backup-uptime-kuma.test.py
They hold a real synthetic SQLite database open in WAL mode. A blind main-file copy demonstrably misses committed monitor/history rows, while the online backup includes them and restores successfully. Other cases cover missing and orphaned installation state, private permissions, password mismatches, credential rotation, concurrent-run locks, refusing overwrite, corrupted file pairs, broken foreign keys and credential-safe subprocess errors.
Docker orchestration and the credential-verifier boundary are mocked in those offline tests. The pinned Kuma 2.5.11 image's actual SQLite driver/password verifier were also checked with matching and mismatching synthetic in-memory users. No production database contents or credentials were read for that check. No live backup, production restore, container restart or notification is performed by the implementation verification.
This covers the database and admin credential file. Ancillary uploaded icons, screenshots, custom TLS files and Docker TLS certificates outside SQLite are not included. The seven provisioned HTTP monitors do not depend on such files; extend capture before adding monitors that do. A full application rehearsal and a verified off-site retrieval remain separate recovery checks. This is not a replacement for PostgreSQL backups, RPO/RTO policy or an external uptime observer.