domverse
792134c72d
Adds the installation manual, architecture overview, and illustrated user manual as a five-story epic, plus the acceptance gate that keeps them true. The documentation is markdown under docs/, so the same files are readable in the repository and rendered by the deployed application at /app/#/docs. An operator who was handed a URL and an access secret has no repository checkout in front of them, and the network the application is deployed to is not assumed to reach a CDN. Two decisions are recorded in the epic rather than left to implementation: - The renderer is vendored (marked), not written and not fetched. - Diagrams are mermaid, rendered client-side, with script-src untouched. Whether mermaid needs 'unsafe-eval' was measured rather than assumed: its bundle contains no eval( and no new Function, and rendered under this application's exact CSP it produced an SVG with no script-src violation. What it does violate is style-src, which gains 'unsafe-inline'. With script-src, img-src, connect-src, and font-src all unchanged, that leaves defacement rather than execution or exfiltration. The alternative -- pre-rendering diagrams to committed SVG with the already-installed Playwright -- is recorded as the migration if that trade is ever refused. Screenshots are generated from the running application, never pasted, and every documented setting, command, exit code, error code, and state is cross-checked against the code that implements it, so stale documentation fails a test instead of misleading an operator. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015csGY8XV1M92fHfKnMmjtu
2.5 KiB
2.5 KiB
US09-02 — Write the Installation and Operations Manual
Epic: E09
As somebody installing this application for the first time, I want one manual that takes me from nothing to a running instance pointed at my photo library, so that I do not have to reconstruct the procedure from the README, the compose file, and the test suite.
Acceptance criteria
- A host installation path: prerequisites and their versions (Python, exiftool,
immich-go, Playwright's browser for the test suite), virtual environment, dependency
install,
.env, database migration, startingserveandworker, and how to verify the install succeeded. - A container installation path: the published image, the compose file, the data
volume, the library bind mount and why it is mounted the way it is, published ports,
running behind a reverse proxy with
PHOTO_PIPELINE_ALLOWED_HOSTSandPHOTO_PIPELINE_TRUSTED_PROXIES, and the Portainer/webhook deployment already in use. - A configuration reference: every
PHOTO_PIPELINE_*setting with its meaning, default, accepted values, and whether it is a secret. Secrets are described, never exemplified with a real-looking value. - A first run checklist that ends in a verified state: library discovered, worker claiming jobs, readiness endpoint green, diagnostics clean.
- Operations: upgrading (including what the migration backup does), backup, verify, restore, pruning, diagnostics, and the log locations for each role.
- Troubleshooting: each refusal an operator can hit at startup — every non-zero exit code of the CLI, the trust-boundary refusal, the unmounted library root refusal, the library lock being held, and a legacy CLI still running — with the cause and the fix.
- The manual states the safety invariants an installer must not work around: one worker
writes,
_IGNORE/is never read, EXIF is verified before upload, and the library lock is authoritative.
Automated tests
- Every
PHOTO_PIPELINE_*setting documented exists as a field onConfig, and every field onConfigis documented — both directions, so a new setting cannot ship undocumented. - Every CLI command and flag named in the manual exists in the argument parser, and every subcommand the parser accepts appears in the manual.
- Every exit code documented is one the CLI can actually return.
- No documented example value collides with a real secret pattern (the repository's own
credential scanner runs over
docs/).
Dependencies
- US09-01