Harden private media and backup recovery; add V2 deployment and migration guides
This commit is contained in:
parent
c549c34f60
commit
ffaa1f6afa
19 changed files with 623 additions and 14 deletions
44
docs/AI.md
Normal file
44
docs/AI.md
Normal 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
96
docs/DEPLOYMENT.md
Normal 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
22
docs/MIGRATION.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue