domverse/photoanalyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

US09-02 — Write the Installation and Operations Manual #103

New Issue
Closed
opened 2026-08-23 15:06:14 +02:00 by domverse · 3 comments
domverse commented 2026-08-23 15:06:14 +02:00
Owner
Copy Link

Source specification: 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
Source specification: [delivery_backlog/stories/US09-02-installation-manual.md](https://git.domverse-berlin.eu/domverse/photoanalyzer/src/branch/main/delivery_backlog/stories/US09-02-installation-manual.md) # 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
domverse self-assigned this 2026-08-23 15:06:15 +02:00
domverse added this to the E09 — Product Documentation milestone 2026-08-23 15:07:40 +02:00
domverse added this to the Photo Analyzer Delivery project 2026-08-23 15:08:52 +02:00
domverse added a new dependency 2026-08-23 15:09:52 +02:00
#102 US09-01 — Serve the Documentation Inside the Application
domverse added a new dependency 2026-08-23 15:10:18 +02:00
#106 US09-05 — Automate Documentation Acceptance
domverse removed their assignment 2026-08-23 15:15:04 +02:00
domverse added status/in-progress and removed status/backlog labels 2026-08-23 21:12:08 +02:00
domverse self-assigned this 2026-08-23 21:12:08 +02:00
domverse commented 2026-08-23 21:12:09 +02:00
Author
Owner
Copy Link

Claimed for implementation on branch us/US09-02-write-the-installation-and-operations-manual.

Claimed for implementation on branch `us/US09-02-write-the-installation-and-operations-manual`.
domverse added status/review and removed status/in-progress labels 2026-08-23 21:45:40 +02:00
domverse commented 2026-08-23 21:45:40 +02:00
Author
Owner
Copy Link

Submitted for review: #108

Tests passed:

  • work_item/scripts/python -m unittest discover -s work_item/tests -v
  • work_item/scripts/python -m pytest tests -q
  • work_item/scripts/python -m pytest tests/integration/test_installation_manual.py tests/integration/test_documentation.py tests/e2e/test_docs_ui.py -q
Submitted for review: https://git.domverse-berlin.eu/domverse/photoanalyzer/pulls/108 Tests passed: - `work_item/scripts/python -m unittest discover -s work_item/tests -v` - `work_item/scripts/python -m pytest tests -q` - `work_item/scripts/python -m pytest tests/integration/test_installation_manual.py tests/integration/test_documentation.py tests/e2e/test_docs_ui.py -q`
domverse added status/done and removed status/review labels 2026-08-23 21:46:04 +02:00
domverse commented 2026-08-23 21:46:05 +02:00
Author
Owner
Copy Link

Completed and merged via PR #108.

Completed and merged via PR #108.
domverse moved this to Done in Photo Analyzer Delivery on 2026-08-23 21:47:15 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/backend
Backend services, jobs, or API
 area/database
Schema, persistence, migration, or queries
 area/documentation
Manuals, architecture notes, and in-app documentation
 area/filesystem
Filesystem identity, mutation, or storage
 area/frontend
Browser UI and client-side application
 area/integration
External tools or provider integrations
 area/testing
Automated test suites, fixtures, and tooling
 priority/critical
Release-blocking safety or correctness
 priority/high
Important phase outcome
 priority/normal
Normal planned work
 status/backlog
Awaiting dependency eligibility or prioritization
 status/blocked
Cannot proceed without an explicit resolution
 status/done
Merged, tested, and completed
 status/in-progress
Currently being implemented
 status/ready
Eligible to be claimed
 status/review
Submitted in a pull request for review
 type/documentation
Written documentation delivered as a product artefact
 type/feature
User-facing or domain capability
 type/hardening
Security, resilience, operations, or release hardening
 type/migration
Donor extraction, migration, or legacy consolidation
 type/test
Automated test infrastructure or acceptance coverage
No Label area/documentation priority/normal status/done type/documentation
Milestone
No items
No Milestone E09 — Product Documentation
Projects
Clear projects
No project Photo Analyzer Delivery
Assignees
Clear assignees
domverse
No Assignees domverse
1 Participants
Notifications
Due Date
No due date set.
Blocks
#106 US09-05 — Automate Documentation Acceptance
domverse/photoanalyzer
Depends on
#102 US09-01 — Serve the Documentation Inside the Application
domverse/photoanalyzer
Reference: domverse/photoanalyzer#103
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?