Backup and restore
All data lives in one folder: ./pb_data next to docker-compose.yml — the SQLite database plus uploaded files. Nothing of yours is stored anywhere else, and nothing is stored inside the container.
The bundled script
./backup.sh # creates kb-backup-YYYY-MM-DD.tgz
./backup.sh restore FILE # restores data from a backupWhat the script does that this page did not say before:
- It backs up while the instance runs — the container is not stopped. The database is taken as a consistent snapshot (
sqlite3 .backupinside the container, one moment in time, no write-ahead log halves), the uploaded files are packed next to it. Earlier versions of the script copied the raw database files of a running instance, which under load could produce an archive with a silently broken index; if you keep such older archives,restorenow checks them (below). An attachment being uploaded at that very second is the one thing that may be missing from the archive — the next run has it. - The backup file gets permissions
600(readable by the owner only) and an unencrypted archive prints the warning the archive is NOT encrypted. - A restore first checks the archive (it refuses paths outside
pb_data/), unpacks it next to the live data, runsPRAGMA integrity_checkon the unpacked database with the instance image'ssqlite3(a damaged archive is refused and the live data stays as it is), only then stops the instance, swaps the folders and starts it again. The old data stays inpb_data.old— delete it once you have checked the restore (rm -rf pb_data.old).
Encrypted backups
The archive holds everything — maps, user accounts, uploaded files. If it ever leaves the server (a download to your laptop, an off-site copy, any cloud storage), encrypt it: export KB_BACKUP_PASSPHRASE and the script writes kb-backup-YYYY-MM-DD.tgz.gpg instead (symmetric GPG, AES-256).
export KB_BACKUP_PASSPHRASE='a-long-passphrase-of-your-own'
./backup.sh # → kb-backup-YYYY-MM-DD.tgz.gpg
./backup.sh restore kb-backup-....tgz.gpg # same passphrase, or gpg asks for itrestore accepts both plain .tgz and .tgz.gpg, so older unencrypted backups keep working. Keep the passphrase outside the server and outside the repository — a password manager is the right place. There is no recovery: without the passphrase the archive is unreadable for everyone, including you.
Regularly, and off the machine
A backup that sits on the same disk as the data survives a deleted container, but not a failed disk. Once a day from cron, and a copy elsewhere:
# crontab -e (the user who owns the instance folder)
0 3 * * * cd /path/to/killbottleneck && KB_BACKUP_PASSPHRASE='…' ./backup.sh >> backup.log 2>&1Then move the kb-backup-*.tgz.gpg files anywhere off the machine — rsync to a NAS, rclone to a cloud, or a manual download once a week. The script does not delete old backups; tidy them yourself (ls kb-backup-*).
By hand
Back up by copying the pb_data folder; restore by putting it back. That is genuinely all there is to it.
docker compose stop
tar czf kb-backup-$(date +%F).tgz pb_data
docker compose startTake one before a bigger update
Database migrations run automatically on start, and they run forward only — going back to an older version means restoring a backup. A backup taken before docker compose up -d --build is the difference between a bad afternoon and a bad week.
Verify the backup, do not assume it
A backup you have never restored is a hypothesis. Unpack it once into a throwaway copy:
mkdir /tmp/kb-restore-test && cd /tmp/kb-restore-test
tar xzf /path/to/kb-backup-2026-10-24.tgz
ls pb_data # you should see data.db and a storage folder with the filesThe real test is restoring it into a second instance (a different KB_NAME and KB_PORT, its own folder) and signing in.
What is not in the backup
.env and docker-compose.override.yml are your configuration, not data — the script does not include them. Keep them somewhere too; without them a restored instance comes up with default ports, no AI, and no Google sign-in. The SMTP settings live in the database (pb_data), so they are in the backup.
A personal export is not an instance backup
My account → My data downloads a JSON with one person's maps and settings — good for moving your own projects, not as a server backup. See Export and import.
Related
- Updating — when you definitely want a backup
- Installation → Where things live
- Export and import — exports from the app

