Backup and restore

Everything worth keeping lives in one directory:

data/
├── kaio.db          # metadata, metrics, events, versions, scans
├── kaio.db-wal      # write-ahead log, part of the database
├── kaio.db-shm      # shared memory index, part of the database
└── stacks/
    └── <name>/
        ├── compose.yml        # the live compose file
        └── .env               # generated, mode 0600, secrets in clear text

Copying the database file is not a backup

SQLite runs in WAL mode. Recent writes live in the -wal file until a checkpoint folds them into the main file, so a plain cp kaio.db taken while the server runs gives you a database missing its latest transactions, or an inconsistent one.

Use SQLite’s own backup, which is safe against a running writer:

sqlite3 data/kaio.db ".backup '/backups/kaio.db'"

Or stop the container first, which checkpoints and removes the -wal:

docker compose stop kaio
tar czf /backups/kaio-$(date +%F).tar.gz data/
docker compose start kaio

Copying the three files together while the server runs also works, provided you copy all three and never just the .db.

The compose files are not in the database

data/stacks/ holds the files Compose actually runs. A backup of the database alone restores the history of your stacks, not the stacks themselves. Take the whole directory.

Restoring

docker compose down
rm -rf data/
tar xzf /backups/kaio-2026-09-24.tar.gz
docker compose up -d

The containers of your stacks are not part of the backup, and they do not need to be: redeploy them from the restored compose files, or let a stack update recreate them.

Version rollback is not supported

Migrations run automatically at startup and only move forward. Once a newer version has opened the database, an older image may fail to start or misread the schema, and there is no downward migration. That makes the backup the only way back, and it has to be taken before the upgrade, not after.

Upgrading is that procedure in order.

What is safe to lose

Metrics are kept for 24 hours and events for 30 days by default, so a backup restores a short window of history no matter when it was taken. The parts that matter over time are the stack files, their versions and their environment. See Data retention.