photoanalyzer/delivery_backlog/stories/US09-02-installation-manual.md

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, starting serve and worker, 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_HOSTS and PHOTO_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 on Config, and every field on Config is 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