Restore a full backup from Settings
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s

Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-16 12:33:42 -07:00
parent e0bc7b580e
commit 7125dec3e0
13 changed files with 521 additions and 72 deletions

View file

@ -94,6 +94,29 @@ cannot read an included file fails rather than silently substituting an empty fi
Avoid changing or deleting source files while making a full ZIP; filesystem content is not
transactional with SQLite.
## Restoring a full backup in the app
Settings → Data → **Restore a full backup** uploads a ZIP from "Download backup" and replaces
everything on the running server: content, progress, uploads, AI models and all settings. No
restart is needed. Steps (`server/services/restore.ts`):
- The ZIP is unpacked into a staging folder inside the data folder. Only `study.db`,
`secret.key`, `manifest.json`, `uploads/*` and `media/*` are accepted.
- The staged database is upgraded to this version's schema. A backup from a newer version is
refused.
- Saved API keys are re-encrypted from the backup's `secret.key` to this server's key, so a
backup from another install keeps its AI connections. Keys sealed with an `APP_SECRET` this
server does not have are reported as unreadable and must be entered again.
- A `pre-restore-*` snapshot of the current database is written, running generations stop, and
the database file is swapped under the open handle.
- Files from the backup are copied over the uploads and media folders. Files already there are
left in place.
- The person restoring stays signed in. Later sign-ins use the backup's password.
The upload is the raw ZIP body (up to 20 GB). A proxy may cap uploads well below that (Cloudflare's
free plan allows 100 MB per request). For a larger backup, restore through the server's own
address on the local network, or use the manual drill below.
## Restore drill
1. Download a full ZIP and verify it opens. Stop the V2 container before restoring.

View file

@ -6,7 +6,10 @@ a separate data folder. It never upgrades a production V1 database in place.
1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself,
stop V1 first; copying only a live WAL-mode `.db` can omit recent writes.
2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume.
3. In V2 Settings → Data → V1 import, select the **backup copy** and preview it.
3. Settings no longer shows the V1 import (its place went to restoring a full V2 backup), but
the endpoint remains. While signed in, preview the **backup copy** with
`POST /api/import/v1?preview=1` (multipart field `file`, header `X-Requested-With: studydesk`),
then import it without `?preview=1`.
4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted
SQLite file read-only and creates new IDs in one transaction. A failed import rolls back.
5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and