Skip to content

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.

  1. 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.
  2. 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.db with private permissions and ownership suitable for that image. Place uptime-kuma-db-config.json alongside it as /app/data/db-config.json, also private. Do not reuse a production volume for a rehearsal.
  3. Restore uptime-kuma-credentials.json.bak as /opt/aim-store/monitoring/.uptime-kuma-credentials.json, mode 600. Restore the monitoring runtime .env from the same full set using the general recovery procedure; do not print it. Keep the dashboard bound to loopback.
  4. 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.
  5. After an authorized production start, verify the private dashboard login, monitor history and notification assignments. bash uptime-kuma/provision.sh --verify and bash 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.