Study/docs/DEPLOYMENT.md
Elijah 7125dec3e0
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Restore a full backup from Settings
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>
2026-11-16 12:33:42 -07:00

8.5 KiB

Single-container deployment and recovery

Unraid

Getting the image

Every push to the v2 branch runs .forgejo/workflows/build-v2.yml. It typechecks and runs the test suite inside the Node 24 image (docker build --target test), builds the production image, smoke-tests it as a fresh non-root container, then publishes two tags:

  • git.elijahkuntz.com/elijah/study:v2 (moves with each successful v2 push)
  • git.elijahkuntz.com/elijah/study:v2-<12-char commit> (fixed; use it to pin or roll back)

It never publishes :latest, which V1's main workflow owns. Keep the V1 container on its existing tag. Do not merge v2 into main until V2 replaces V1: that merge would remove V1's workflow, and this one only triggers on v2. The workflow can also be run manually.

Alternatively build locally from this checkout with docker build -t study-desk:v2-local ..

Container settings

Create a new container named study-v2, image git.elijahkuntz.com/elijah/study:v2 (or your local tag):

Setting Value
Network bridge
Container port 3726 TCP
Host port 3727 (or another unused port)
Container path /data
Host path /mnt/user/appdata/study-v2
TZ America/Phoenix
TRUST_PROXY true only behind a trusted proxy
COOKIE_SECURE true with HTTPS; auto for local HTTP testing

The image uses UID/GID 1000:1000. Unraid appdata folders are normally owned by nobody:users (99:100), which that user cannot write to. Pick one:

  • Create the dedicated folder and hand it to 1000: mkdir -p /mnt/user/appdata/study-v2 then chown 1000:1000 /mnt/user/appdata/study-v2. Only change permissions on this new folder.
  • Or keep Unraid's ownership and add --user 99:100 to the container's Extra Parameters.

If the container restarts repeatedly with a permissions error in its log, this is the cause. Never mount V1's database or data folder.

The supplied compose.yaml defaults to ./data-v2 and host port 3727. Override STUDY_DATA_DIR for Unraid. Do not reuse a V1 container name, mount or proxy destination.

Startup applies committed schema migrations transactionally, taking a database snapshot first when an existing V2 schema needs upgrading. A database from a newer app version is refused. The first visit asks for the setup code from the container log or /data/setup-code.txt. After setup, the password is stored as a salted scrypt hash. No registration exists.

Reverse proxy

Point your proxy to the container's port 3726 (or the host's mapped port). Forward Host, X-Forwarded-Proto, and a trustworthy X-Forwarded-For. With TRUST_PROXY=true, restrict direct access to the application to your proxy/network: forwarded headers are trusted. Use COOKIE_SECURE=true for the HTTPS public hostname. Plain HTTP cannot carry Secure cookies. Keep proxy upload limits at least as large as MAX_UPLOAD_MB, and allow long AI responses. Disable buffering for /api/ai/chat and /api/ai/explain; allow a long read timeout there. Share-link AI is limited to a region by visitor address, so the proxy must pass the real one (Settings → Sharing warns when every visitor looks local). Behind Cloudflare, the CF-IPCountry header (and CF-Region-Code, from the "Add visitor location headers" managed transform) is used directly; otherwise the server downloads the DB-IP Lite database into /data/geoip monthly and needs outbound HTTPS to download.db-ip.com or cdn.jsdelivr.net. Do not cache /api/, /media/ or shared study data. /api/health returns 200 when SQLite works.

Configuration

.env.example documents all server variables. Environment values override a local .env. The image excludes local configuration, source databases and test content from its build context. Do not bake passwords or keys into an image.

  • ADMIN_PASSWORD: optional first-install password, ignored after setup.
  • RESET_ADMIN_PASSWORD: changes the password and revokes sessions at startup. Remove it after one successful reset or it will repeat on every restart.
  • APP_SECRET: optional external encryption secret (16+ characters). Keep it stable. Otherwise /data/secret.key is generated once. A damaged key is refused, never replaced.
  • MAX_UPLOAD_MB: default 100; OCR/native vision input has additional provider limits.
  • BACKUP_KEEP: default 7 daily automatic database snapshots.

Backups

Settings → Data has portable content JSON and a full ZIP download. JSON includes quizzes, decks, classes, folders and notes, not progress, uploads, credentials or all settings. The full ZIP contains a consistent SQLite snapshot, uploads, media, a restore manifest and the generated secret.key when present. It contains private content and credential material; store it securely. An externally configured APP_SECRET must be saved separately.

Daily snapshots under /data/backups cover the database only. They are not a substitute for a full off-machine backup of the data volume and encryption key. A backup stream that cannot read an included file fails rather than silently substituting an empty file. 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.
  2. Keep the old data folder intact. Extract the ZIP into a new, empty folder.
  3. Check that study.db, uploads/, media/ and the matching key are present as applicable. If using APP_SECRET, set the original value. Do not copy stale study.db-wal or study.db-shm files from another database into the restored folder.
  4. Give the container user access. Start the same image version with the new folder mounted at /data, initially on a separate port without public routing.
  5. Verify login, class/quiz/deck counts, representative uploads, review progress, AI connection decryption and shared links. Use SQLite PRAGMA integrity_check and foreign_key_check if manually inspecting a copy. Do not run migration/reset experiments on your only backup.
  6. Switch proxy routing only after these checks succeed. Retain the previous folder and image.

For an upgrade, make and verify a full backup first, then rebuild/recreate the container with the same V2 volume. Never edit an already applied migration. Roll back by restoring the pre-upgrade data into a separate directory with the prior image; do not force an older image to open a newer schema.

Verification still required on Unraid

Docker Desktop is now installed in the development VM. The image builds, and a disposable container passed non-root startup, login, class/card/document persistence across restart, full ZIP download, anonymous deck sharing and private API denial. These checks used a new test volume, which was removed afterward. Unraid has not been tested. Before production use: confirm health status and non-root volume permissions, complete setup over HTTPS, upload a PDF and PPTX, restart and check persistence, test public links from a private browser, confirm proxy streaming and upload limits, and perform the restore drill above. The Dockerfile and Compose configuration are implemented and verified locally; no production deployment has occurred.