# US09-02 — Write the Installation and Operations Manual

Epic: [E09](../E09-documentation.md)

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