- Malformed model JSON is sent back for repair, then retried; a failed job starts over once before it fails. Visitors can dismiss failed sets. - Generated sets get a short distinct name and description; flashcards are atomic and have no hints; standard study shows known/learning counts. - Share links: "In progress" list, finished sets join the normal lists with a "New" tag, plain progress steps, newest exam first. - Share-link AI expires after a week, can be limited to the US or Arizona (DB-IP Lite or Cloudflare headers) and is locked by abuse protection (migration 8). - The assistant never answers from general knowledge; MCP and web search tools load without a manual test. - Plain-text copy, no question count in exam mode, filler text removed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.1 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 successfulv2push)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-v2thenchown 1000:1000 /mnt/user/appdata/study-v2. Only change permissions on this new folder. - Or keep Unraid's ownership and add
--user 99:100to 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.keyis 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
- Download a full ZIP and verify it opens. Stop the V2 container before restoring.
- Keep the old data folder intact. Extract the ZIP into a new, empty folder.
- Check that
study.db,uploads/,media/and the matching key are present as applicable. If usingAPP_SECRET, set the original value. Do not copy stalestudy.db-walorstudy.db-shmfiles from another database into the restored folder. - 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. - Verify login, class/quiz/deck counts, representative uploads, review progress, AI connection
decryption and shared links. Use SQLite
PRAGMA integrity_checkandforeign_key_checkif manually inspecting a copy. Do not run migration/reset experiments on your only backup. - 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.