47 lines
2.5 KiB
Markdown
47 lines
2.5 KiB
Markdown
# 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
|