From 071b7e9b01e41d4048b1bbb3d9caaac4c8a526de Mon Sep 17 00:00:00 2001 From: Anders Betts Date: Thu, 17 Sep 2026 21:48:00 +0200 Subject: Add token login to bokfctl and enforce admin scope for tokens - bokfctl: --token / BOKFD_TOKEN via client_token_login - tokens must carry the admin scope for admin commands (was bypassed) - docs: token-based snapshot for restic backups --- docs/DEPLOY.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'docs/DEPLOY.md') diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 8d36453..eb3ec1c 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -170,12 +170,42 @@ Develop against this org; agents get their own API token ## Backup and restore +`backup.snapshot` makes a consistent copy of the live WAL database with +`VACUUM INTO`; the result lands in `var/db/backup/` as +`bokfd-.db` (the response carries its SHA-256). Interactive: + ```sh docker compose exec -e BOKFD_PASSWORD='' bokfd \ bokfctl --user admin backup.snapshot -ls var/db/backup # -.db + .sha256 +ls var/db/backup +``` + +For unattended backups (restic, cron) use an admin-scoped token instead of +the password, created once: + +```sh +docker compose exec -e BOKFD_PASSWORD='' bokfd \ + bokfctl --user admin token.create '{"label":"backup","scopes":["admin"]}' +# store the token (shown once) in a root-only file, e.g. /etc/bokf/bokfd-backup.env: +# BOKFD_TOKEN=bokf_... ``` +Then, before every restic run: take a snapshot through the daemon and let +restic read only the snapshots — never the live database: + +```sh +. /etc/bokf/bokfd-backup.env +docker compose --project-directory /mnt/data/bokf exec -T -e BOKFD_TOKEN \ + bokfd bokfctl backup.snapshot >/dev/null +find /mnt/data/bokf/var/db/backup -name 'bokfd-*.db' -mtime +14 -delete +restic backup --exclude='/mnt/data/bokf/var/db/bokfd.db*' \ + --exclude='/mnt/data/bokf/var/run' /mnt/data/bokf +``` + +The WAL and shared-memory files (`bokfd.db-wal`, `bokfd.db-shm`) must be +excluded together with the main file; an inconsistent copy of a live SQLite +database is worse than no backup. + Restore: ```sh -- cgit v1.3