Study/docs/DEPLOYMENT.md
Elijah 917954d12d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
Sign-in lockout with console unlock, and forgotten-password reset
- Wrong passwords in a row are counted across every device and kept in
  the database. The first 3 are free; from the 3rd the next attempt
  waits 15 s, 30 s, 1, 2, 5, 15 and 30 minutes; the 10th locks sign-in
  until the unlock code printed to the server log (and saved to
  unlock-code.txt) is entered. Signed-in devices keep working. Only one
  password check runs at a time, so parallel guesses cannot skip a wait.
- "Forgot password?" prints a reset code to the log (reset-code.txt),
  valid once for 15 minutes. It sets a new password, signs out every
  device, lifts any lockout and signs in. Asking again while a code is
  valid prints nothing new.
- Codes are stored hashed; wrong codes count toward the per-address
  limit. RESET_ADMIN_PASSWORD also lifts a lockout.
- Sign-in page: a live countdown during a wait, an unlock step and a
  reset step.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 15:46:16 -07:00

9.8 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.

Sign-in lockout and password reset

Wrong passwords are counted in a row across every device, and the count is kept in the database, so restarting does not clear it. The first 3 are free. From the 3rd, the next attempt must wait 15 s, then 30 s, 1, 2, 5, 15 and 30 minutes. The 10th wrong password locks sign-in. Devices that are already signed in keep working. To lift a lockout, enter the unlock code on the sign-in page. It is printed to the container log (docker logs <container>) and saved to /data/unlock-code.txt. Lifting the lockout does not sign you in, and the count starts again. A correct password also starts the count again.

Forgot password? on the sign-in page prints a reset code to the log and saves it to /data/reset-code.txt. Asking again while a code is valid prints nothing new. The code works once, for 15 minutes. It sets a new password, signs out every device, lifts any lockout and signs you in. Both codes need access to the server, as the setup code does. Wrong codes count toward the per-address limit (8 in 15 minutes).

Anyone who can reach the sign-in page can use up the 10 attempts and lock it. A lockout never reveals or weakens the password, and the console code always gets you back in. RESET_ADMIN_PASSWORD (below) still works too and also lifts a lockout.

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.