Skip to content

Backup and Restore Playbook

Jump to bottom
Chris Nighswonger edited this page Mar 2, 2026 · 1 revision

Backup and Restore Playbook

This playbook covers Kanfei's built-in backup system and manual recovery procedures.

Built-In Backup System

Kanfei includes a backup service that creates compressed archives containing the database, custom backgrounds, and a manifest. Backups can be triggered via the Settings UI, API, or CLI.

Automatic Backups

Enable automatic backups in Settings > Backup:

  • backup_enabled — toggle automatic backups on/off
  • backup_interval_hours — how often to run (6h to weekly)
  • backup_retention_count — how many backups to keep (oldest rotated out)

The scheduler runs as a background task inside the web app. Each backup performs a WAL checkpoint for database consistency before copying.

Manual Backup

From the CLI:

python station.py backup
python station.py backup --output /path/to/backup.tar.gz

From the API:

curl -s -X POST http://localhost:8000/api/backup | jq .

From the UI: Settings > Backup > "Backup Now" button.

Listing Backups

curl -s http://localhost:8000/api/backup/list | jq .

Or view the list in Settings > Backup.

Downloading a Backup

curl -L http://localhost:8000/api/backup/download/<backup-name> -o backup.tar.gz

Restore

From the CLI:

python station.py restore --input /path/to/backup.tar.gz

From the API:

curl -s -X POST http://localhost:8000/api/backup/restore \
  -F "file=@backup.tar.gz" \
  -F "confirm=RESTORE" | jq .

From the UI: Settings > Backup > select a backup > Restore (requires typing RESTORE to confirm).

A pre-restore safety copy (.pre-restore) is created automatically before every restore.

After restoring, restart both the web app and logger daemon.

Deleting a Backup

curl -s -X DELETE http://localhost:8000/api/backup/<backup-name> | jq .

What Gets Backed Up

The backup archive includes:

  • SQLite database (after WAL checkpoint)
  • Custom background images
  • Manifest with timestamp, version, and file list

Configuration (.env / /etc/kanfei/kanfei.conf) is not included in the archive — back this up separately.

Manual Backup (File-Level)

If you prefer manual file-level backups:

  1. Stop services briefly for consistency (or rely on WAL mode).
  2. Copy the DB and config files.
# Adjust paths to match your deployment
cp /var/lib/kanfei/kanfei.db /backup/kanfei/kanfei-$(date +%F-%H%M).db
cp /etc/kanfei/kanfei.conf /backup/kanfei/conf-$(date +%F-%H%M).txt

The legacy DB export endpoint is also still available:

curl -L http://localhost:8000/api/db-admin/export/backup -o kanfei-backup.db

Restore Procedure (Manual)

  1. Stop Kanfei services.
  2. Restore DB file to configured db_path.
  3. Restore config and asset files.
  4. Ensure ownership/permissions are correct.
  5. Start services.
  6. Validate core endpoints.
curl -s http://localhost:8000/api/station | jq .
curl -s http://localhost:8000/api/current | jq .

Backup Frequency

Suggested baseline:

  • enable automatic backups with a daily or 12-hour interval
  • pre-upgrade backup (manual or automatic)
  • additional snapshots before destructive DB admin actions

Retention Guidance

Use the built-in retention rotation (backup_retention_count) to limit disk usage. For additional off-host retention:

  • daily backups for 14–30 days
  • weekly backups for 8–12 weeks
  • monthly backups for long-term retention

Failure Scenarios and Response

Corrupted DB suspected

  • stop writes immediately
  • restore latest backup (built-in or manual)
  • preserve corrupted copy for analysis

Host failure

  • provision replacement host
  • restore backup archive or DB/config files
  • revalidate hardware connection and permissions (serial device access or network reachability)

Accidental data purge/compact error

  • stop instance
  • restore pre-maintenance snapshot
  • verify recovered data before resuming normal operation

Related Pages

Clone this wiki locally