All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
- 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>
168 lines
9.8 KiB
Markdown
168 lines
9.8 KiB
Markdown
# 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.
|