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