Harden private media and backup recovery; add V2 deployment and migration guides

This commit is contained in:
Elijah 2026-11-11 19:31:32 -07:00
parent c549c34f60
commit ffaa1f6afa
19 changed files with 623 additions and 14 deletions

44
docs/AI.md Normal file
View file

@ -0,0 +1,44 @@
# AI connections and verification
Settings → AI manages provider connections and model routing. Add a connection, test it,
discover models where supported (or add a custom model), enable models and select defaults
for generation, chat, explanations and vision. Output limits, capabilities, pricing and
reasoning settings can be edited per model. Catalog prices are estimates, not billing records.
Adapters use OpenAI Responses, Anthropic Messages, Gemini generateContent, OpenAI-compatible
Chat Completions and Ollama's native chat API. Configure the endpoint as shown in Settings.
Local models are reached **from the server/container**: `localhost` inside Docker is the
container itself, not your workstation or Unraid host. Use a reachable LAN address instead.
Keys are encrypted with AES-256-GCM in SQLite using `/data/secret.key` or `APP_SECRET`.
Only the server decrypts them. Keep the key with backups; changing it breaks decryption.
Documents are sent to the selected provider when you request AI processing; extraction and
full-text indexing otherwise run locally. OCR requires a compatible vision/PDF model.
Retrieval uses chunked SQLite FTS search; it is lexical retrieval, not embedding similarity.
Review generated nursing content and source references before using it for study.
## ChatGPT account investigation (2026-11-11)
The official [Sign in with ChatGPT quickstart](https://developers.openai.com/siwc/quickstart)
now describes plan access for eligible integrations. The
[official implementation guide](https://developers.openai.com/cookbook/articles/sign-in-with-chatgpt)
distinguishes local personal/open-source tools from remotely hosted apps, which require
access approval. This Unraid/reverse-proxy deployment is a hosted web application; eligibility
for its private client has not been established. Therefore V2 currently uses conventional API
connections, and does not advertise ChatGPT plan access or reuse another client's credentials.
To add this later, obtain the appropriate approval/registration and implement the documented
OAuth/PKCE flow, verified identity, encrypted refresh tokens, approved callbacks and plan-scoped
model discovery. Keep this separate from the single administrator's local login. Never copy
ChatGPT browser session tokens or a Codex client's registration/credentials into Study Desk.
## What has been tested
Mock protocol tests cover request translation, streams, tools, usage and error handling.
Integration tests use a local OpenAI-compatible mock to generate/edit/save drafts, search
documents with citations and exercise confirmed assistant actions. They cost no API credits.
No successful real-provider inference or real ChatGPT OAuth authorization is claimed.
For manual local AI testing: `npx tsx scripts/mock-ai.ts` starts a scripted mock at
`http://localhost:4010/v1` with key `mock-key`. It returns clearly labeled synthetic material.
Do not use mock output as nursing guidance. Stop the mock and remove its connection after QA.

96
docs/DEPLOYMENT.md Normal file
View file

@ -0,0 +1,96 @@
# Single-container deployment and recovery
## Unraid
Build from this checkout with `docker build -t study-desk:v2-local .`.
Create a **new** container named `study-v2`, image `study-desk:v2-local`:
| 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**. Create a dedicated host directory writable by that user
before starting. For example, on Unraid: `mkdir -p /mnt/user/appdata/study-v2` then
`chown 1000:1000 /mnt/user/appdata/study-v2`. Only change permissions on this new folder.
Alternatively select an appropriate non-root UID/GID using Docker's `--user` option and grant
that identity access to the dedicated directory. 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 is unavailable in the development VM. Before production use: build the image, 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, but container deployment has **not** been executed here.

22
docs/MIGRATION.md Normal file
View file

@ -0,0 +1,22 @@
# Importing V1 safely
V1 code remains on `main` at `7bd0a9a` and in history. V2 has a separate schema and must use
a separate data folder. It never upgrades a production V1 database in place.
1. Use V1's backup facility to make a consistent SQLite copy. If copying files yourself,
stop V1 first; copying only a live WAL-mode `.db` can omit recent writes.
2. Keep the original and a verified backup untouched. Start V2 with an empty V2 volume.
3. In V2 Settings → Data → V1 import, select the **backup copy** and preview it.
4. Review the reported counts/skipped items, then explicitly import. V2 opens the submitted
SQLite file read-only and creates new IDs in one transaction. A failed import rolls back.
5. Compare class/folder/deck/quiz counts and representative questions, rationales, attempts and
scheduling. V1's passwords, provider settings and share URLs are not reused. Recreate links
deliberately. Running the import again creates another set of content.
The importer supports V1 classes, material groups, decks/cards, quiz sets/questions/options,
completed attempts, spaced-repetition card state and activity where present. It reports
unsupported/skipped records. Older optional game features are not migrated as games.
V1 JSON quiz/flashcard exports can also be pasted/uploaded in a class's Import dialog.
Portable V2 JSON exports are useful for migration between apps; full ZIP backups are needed
to preserve progress, documents, settings and credentials. See DEPLOYMENT.md for recovery.