docs: full documentation overhaul — user manual, tutorials, and developer docs - #13
Merged
Conversation
…raceful SIGTERM The server side already compiled and tested green on Linux (ubuntu CI); this makes it actually usable there, with zero changes to any Windows code path (all edits are cfg(unix)-gated, env-gated, or new CI jobs): - release.yml: new independent `linux-tarball` job — builds x86_64, bundles the pinned Meilisearch (same version as the MSI), smoke-tests the packaged binary (boot + HTTP + SIGTERM), and attaches SearchBox-<ver>-x86_64-linux.tar.gz + .sha256 to the release. No `needs:` edge; a Linux failure can never block the MSI legs, and the asset name can't collide with the updater/winget `.msi` matching. - Fixed Docker: the app now honors MEILI_MASTER_KEY when set. Since the v0.3.16 key rotation the app generated its own key and never read the env var the container starts Meilisearch with — every Meili call in Docker was rejected. Env absent (Windows/native) → behavior unchanged. - SIGTERM handling (cfg(unix)): `docker stop` and systemd stops now do the same graceful drain as Ctrl-C instead of hanging as PID 1 until SIGKILL and orphaning the sidecar. Verified: TERM → clean exit in ~1s. - Meilisearch discovery on unix falls back to /usr/local/bin, /usr/bin, /opt/meilisearch, ~/.cargo/bin after the sibling check. Windows stays sibling-only (the MSI guarantees it). - Linux data dir: XDG_DATA_HOME/searchbox (else ~/.local/share) unless running from a cargo target/ dir — no more scattering searchbox.db, vault/ and meili_data/ into whatever cwd the app was launched from. Windows branch untouched. - /api/update/check returns no download_url off Windows, so Settings hides the in-app Install button (the apply endpoint was a stub there). - Inlined three format! args that clippy 1.88 now rejects (-D warnings) in untouched files, so CI stays green when its toolchain catches up. - Docs: README native-Linux section, BUILD.md tarball/Docker-key notes, CHANGELOG entries. Verified: cargo check debug+release and fmt on Windows; cargo check, clippy -D warnings, and the full 61-test suite in a rust:1.88 Linux container; end-to-end packaged-binary smoke test (boot, /login 200, SIGTERM graceful drain) in the same container.
…oper docs New docs/manual/ — written for non-technical readers, screenshot-guided: - Guides: getting started, searching (the :: filter language, syntax colors), images & Explore & the viewer, the private vault, folders & archives (ZIM/ZIP), AI summaries, bookmarks & history, a full Settings tour, Linux & Docker, and a problem→cause→fix troubleshooting page. - Tutorials: your first search, offline Wikipedia (Kiwix ZIM), lock your tax documents in the vault, and free local AI summaries with Ollama. - SCREENSHOTS.md: a session-grouped shot list — every image placeholder in the manual with exact capture instructions and stable filenames (images land in docs/manual/img/, which is NOT embedded in the binary). New docs/dev/ — for developers: architecture (process model, Meili sidecar, storage layout, auth, indexing pipeline, updater, embedding), the HTTP API surface (verified route-by-route against src/routes/), frontend conventions (XSS discipline, animation fill-mode rule, the demo-replica contract), and the local dev workflow. Wiring: README gains a Documentation section; the landing page nav and footer link the manual. All internal page links verified (0 broken); every UI label fact-checked against templates/ and static/js/.
CI run #82 (cargo audit job) failed: 6 vulnerabilities, all from two
freshly-published RUSTSEC advisories (2026-06-29) on quick-xml:
- RUSTSEC-2026-0194: quadratic-time duplicate-attribute-name check
- RUSTSEC-2026-0195: unbounded namespace-decl allocation → memory DoS
Three copies of quick-xml were flagged in Cargo.lock:
- 0.36.2 — our DIRECT dep, used in read_docx to parse uploaded DOCX.
Reachable + attacker-controlled input → bumped to 0.41.0 (fixed).
Adapted the one breaking API change: BytesText::unescape() was
removed in 0.41; replaced with xml10_content() (decodes + unescapes
+ normalizes EOLs; DOCX document.xml is UTF-8 so decode errors are
unreachable).
- 0.31.0 — transitive via calamine 0.26.1 (xlsx/ods reader). DoS-only,
self-DoS by the authenticated uploader. Cannot bump: calamine 0.26
pins ^0.31; the 0.26→0.35 jump's API churn risks the extractor, so
it's a tracked follow-up, not a triage fix. Documented + ignored.
- 0.39.4 — transitive via wayland-scanner ← rfd, which is
cfg(windows)-gated. Not compiled on the Linux server/CI build →
lockfile-only, no reachable code path. Documented + ignored.
.cargo/audit.toml gains the two advisory IDs with full reasoning, in
the repo's existing documented-ignore convention. Verified locally:
cargo fmt --check, cargo clippy -D warnings, cargo test (61 passed),
and cargo audit all pass.
Follow-up (out of scope here): upgrade calamine 0.26 → 0.35 to clear
the last transitive quick-xml 0.31.0 and drop the ignore entries.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #11 (retargets to master when it merges).
docs/manual/ — a real user manual, written for non-technical readers:
SCREENSHOTS.md— a session-grouped shot list with exact capture instructions, ready to work through. Images go indocs/manual/img/, which is deliberately outside the binary's embed globs.docs/dev/ — developer docs: architecture (verified against src/), a route-by-route HTTP API reference, frontend conventions (XSS discipline, the animation fill-mode rule, the landing-demo replica contract), and the dev workflow.
Wiring: README Documentation section; landing nav + footer link the manual. Every internal page link checked (0 broken); UI labels fact-checked against
templates/andstatic/js/.🤖 Generated with Claude Code