Instance backup with restore by CLI (#109) #122

Merged
miko merged 2 commits from feature/109-instance-backup into development 2026-11-05 18:26:05 +01:00
Owner

Closes #109.

  • Download backup in the admin menu (GET /admin/backup, admins only, 404 otherwise). It streams the whole instance as a ZIP, one file at a time, as the download proceeds: backup.json with users, settings, categories with their images, guides (working copy, all versions, deleted ones), pages with their images and the menu, plus every original, variant and attachment under its storage key.
  • Format extends the guide packages (ADR-0022) and shares their format version, now PACKAGE_FORMAT_VERSION, with one shared readFormatVersion. Backups from a newer kataba are refused.
  • Restore runs as npm run restore -- <backup.zip> in the container, and only into an empty instance (no users, settings, categories, guides, pages or menu items). Files are written first, then all data in one transaction; on failure the files are removed and the database stays empty. Guides, categories, pages, steps, images and menu items keep their ids, so links and QR labels keep working. Annotations get new ids, and search texts are rebuilt.
  • The CLI is bundled with rolldown into dist/restore.mjs. Everything is bundled except Prisma, which comes from the standalone server's node_modules. The Dockerfile builds and copies it, and the Lingui macro plugin is now shared with vitest (linguiMacroPlugin.mjs).
  • New dependencies: yazl 3.3.1 and yauzl 3.4.0, because fflate writes no ZIP64 and multi-GB backups need it; dev dependency rolldown 1.2.16. ImageStorage gained size.
  • Docs: ADR-0023, a note in ADR-0013 (the read-only REPEATABLE READ snapshot), GLOSSARY entry "Backup", a README section "Backup and restore" with the new scripts, and a CHANGELOG entry.

Tests: backup description and format version, which files a backup contains, writing a backup ZIP and reading it back, storage size, and e2e for the admin download and the 404 for others. Typecheck, lint, all 552 unit tests and all 69 e2e tests pass.

Manual round trip: I backed up the dev database, restored it into an emptied scratch database, and backed it up again. backup.json is identical apart from its timestamp, all files match byte for byte, and the search texts match. A restore into a database that already had data was refused without writing any files.

Not verified: the restore inside a built image, because the image does not build on development either (#121).

🤖 Generated with Claude Code

Closes #109. - **Download backup** in the admin menu (`GET /admin/backup`, admins only, 404 otherwise). It streams the whole instance as a ZIP, one file at a time, as the download proceeds: `backup.json` with users, settings, categories with their images, guides (working copy, all versions, deleted ones), pages with their images and the menu, plus every original, variant and attachment under its storage key. - **Format** extends the guide packages (ADR-0022) and shares their format version, now `PACKAGE_FORMAT_VERSION`, with one shared `readFormatVersion`. Backups from a newer kataba are refused. - **Restore** runs as `npm run restore -- <backup.zip>` in the container, and only into an empty instance (no users, settings, categories, guides, pages or menu items). Files are written first, then all data in one transaction; on failure the files are removed and the database stays empty. Guides, categories, pages, steps, images and menu items keep their ids, so links and QR labels keep working. Annotations get new ids, and search texts are rebuilt. - The CLI is bundled with rolldown into `dist/restore.mjs`. Everything is bundled except Prisma, which comes from the standalone server's `node_modules`. The Dockerfile builds and copies it, and the Lingui macro plugin is now shared with vitest (`linguiMacroPlugin.mjs`). - New dependencies: `yazl` 3.3.1 and `yauzl` 3.4.0, because fflate writes no ZIP64 and multi-GB backups need it; dev dependency `rolldown` 1.2.16. `ImageStorage` gained `size`. - Docs: ADR-0023, a note in ADR-0013 (the read-only REPEATABLE READ snapshot), GLOSSARY entry "Backup", a README section "Backup and restore" with the new scripts, and a CHANGELOG entry. Tests: backup description and format version, which files a backup contains, writing a backup ZIP and reading it back, storage `size`, and e2e for the admin download and the 404 for others. Typecheck, lint, all 552 unit tests and all 69 e2e tests pass. Manual round trip: I backed up the dev database, restored it into an emptied scratch database, and backed it up again. `backup.json` is identical apart from its timestamp, all files match byte for byte, and the search texts match. A restore into a database that already had data was refused without writing any files. Not verified: the restore inside a built image, because the image does not build on `development` either (#121). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Admins download the whole instance as a streamed ZIP under "Download
backup" in the admin menu: users, settings, categories, guides with
working copies, all versions and deleted ones, pages, the menu and every
stored file, in the guide package format with the shared format version.
`npm run restore -- <backup.zip>` restores it into an empty instance only,
keeping every id. Written with yazl for ZIP64, read with yauzl; the CLI is
bundled with rolldown into dist/restore.mjs for the production image.
ADR-0023, glossary entry Backup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Share the format version check and package file rule with guide
packages, reuse VARIANTS and jsonColumn, warn about files missing from
the storage, and correct the docs: annotations get new ids, ADR-0013
names the REPEATABLE READ exception, README lists the new scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit 2c47b8005c into development 2026-11-05 18:26:05 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!122
No description provided.