marcel/familienarchiv
1
0
Fork 0
Code Issues 117 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(legibility): write docs/DEPLOYMENT.md as Day-1 production checklist (DOC-5) #436

New Issue
Closed
opened 2026-05-05 21:08:15 +02:00 by marcel · 1 comment
marcel commented 2026-05-05 21:08:15 +02:00
Owner
Copy Link

Part of #394 (Epic 2 — Documentation). Rubric checks: C9.1 (Major), C9.2 (Major). Per #394 Decision Queue D1: DOC-5 is a single-page entry-point that links into existing infrastructure docs, not a duplicate.

Problem

An operator deploying Familienarchiv for the first time needs a sequential checklist — not a reference manual. The four docs/infrastructure/*.md docs (ci-gitea.md, production-compose.md, s3-migration.md, self-hosted-catalogue.md) are reference material; they're invisible from the front door. Per Tobias, DOC-5 is the entry-point operators land on first.

Per Nora, DOC-5 must explicitly cover secret management: which env vars are dangerous (have dev defaults), which are fail-fast (must be set or the app crashes), and where MinIO root vs service-account credentials apply.

Scope

  1. Create docs/DEPLOYMENT.md.
  2. Required structure (Day-1 checklist, sequential):
    • Prerequisites — Docker Engine version, ports (80/443/8080/9000/9001/8000), DNS, optional Caddy/Nginx reverse proxy.
    • Secrets checklist (per Nora) — every env var that must be set before first run, classified:
      • Fail-fast (app crashes if missing): DB password, Spring Session secret, OCR X-Training-Token.
      • Dangerous dev defaults (silent fallback to insecure values): MinIO root user/password, MinIO service-account credentials.
      • For MinIO: state explicitly that the application should use a service-account, not root credentials. Flag as "production hardening required" if not yet implemented.
    • Bring-up commands — docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d (or whatever the production overlay is). Link to docs/infrastructure/production-compose.md for the full file.
    • Health verification — /health endpoints, OCR cold-start 30–60s warning (per Tobias: model loading), docker compose ps checks.
    • First-run database seed — initial admin user creation.
    • Operational sections — short paragraphs each linking to:
      • docs/infrastructure/s3-migration.md (storage migration)
      • docs/infrastructure/ci-gitea.md (CI runner)
      • docs/infrastructure/self-hosted-catalogue.md (full self-hosted stack inventory)
      • docs/security-guide.md (production hardening)
    • Cost — per Tobias: include the ~23 EUR/month figure so future maintainers understand the infrastructure budget.
  3. Link from README.md (DOC-1) under "I want to run it locally / in production."
  4. Operational scripts (scripts/clean-e2e-data.sh, download-paperless.sh, flatten-paperless.sh, reset-db.sh) — DOC-7 decides whether they live here ("Operational scripts") or in CONTRIBUTING.md ("Development scripts").

References

Acceptance criteria

  • docs/DEPLOYMENT.md exists.
  • Behavioural test (per Elicit): a developer who has never run the system can follow DOC-5 alone to bring the production stack to a healthy state on a fresh VPS.
  • "Secrets checklist" lists every must-set env var with fail-fast vs dev-default classification.
  • Every operational section either contains the content or links to the canonical infrastructure doc — no duplication.
  • Linked from README.md.
  • Rubric C9.1, C9.2 PASS verified by reviewer.

Definition of Done

DEPLOYMENT.md is on main. Behavioural test passes (verifiable by handing the doc to someone unfamiliar with the stack). Rubric C9.1, C9.2 PASS.

Part of #394 (Epic 2 — Documentation). Rubric checks: C9.1 (Major), C9.2 (Major). Per #394 Decision Queue **D1**: DOC-5 is a single-page **entry-point that links into existing infrastructure docs**, not a duplicate. ## Problem An operator deploying Familienarchiv for the first time needs a sequential checklist — not a reference manual. The four `docs/infrastructure/*.md` docs (`ci-gitea.md`, `production-compose.md`, `s3-migration.md`, `self-hosted-catalogue.md`) are reference material; they're invisible from the front door. Per Tobias, DOC-5 is the entry-point operators land on first. Per Nora, DOC-5 must explicitly cover **secret management**: which env vars are dangerous (have dev defaults), which are fail-fast (must be set or the app crashes), and where MinIO root vs service-account credentials apply. ## Scope 1. Create `docs/DEPLOYMENT.md`. 2. Required structure (Day-1 checklist, sequential): - **Prerequisites** — Docker Engine version, ports (80/443/8080/9000/9001/8000), DNS, optional Caddy/Nginx reverse proxy. - **Secrets checklist** (per Nora) — every env var that must be set before first run, classified: - **Fail-fast** (app crashes if missing): DB password, Spring Session secret, OCR `X-Training-Token`. - **Dangerous dev defaults** (silent fallback to insecure values): MinIO root user/password, MinIO service-account credentials. - For MinIO: state explicitly that the application should use a service-account, not root credentials. Flag as "production hardening required" if not yet implemented. - **Bring-up commands** — `docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d` (or whatever the production overlay is). Link to `docs/infrastructure/production-compose.md` for the full file. - **Health verification** — `/health` endpoints, OCR cold-start 30–60s warning (per Tobias: model loading), `docker compose ps` checks. - **First-run database seed** — initial admin user creation. - **Operational sections** — short paragraphs each linking to: - `docs/infrastructure/s3-migration.md` (storage migration) - `docs/infrastructure/ci-gitea.md` (CI runner) - `docs/infrastructure/self-hosted-catalogue.md` (full self-hosted stack inventory) - `docs/security-guide.md` (production hardening) - **Cost** — per Tobias: include the ~23 EUR/month figure so future maintainers understand the infrastructure budget. 3. Link from `README.md` (DOC-1) under "I want to run it locally / in production." 4. Operational scripts (`scripts/clean-e2e-data.sh`, `download-paperless.sh`, `flatten-paperless.sh`, `reset-db.sh`) — DOC-7 decides whether they live here ("Operational scripts") or in CONTRIBUTING.md ("Development scripts"). ## References - Parent: #394 - Rubric: C9.1, C9.2 - Existing docs (link, don't duplicate): `docs/infrastructure/*.md`, `docs/security-guide.md` - Inputs to migrate (DOC-7): `infra/CLAUDE.md`, `scripts/CLAUDE.md` - Memory: `Spring 7 kills @Lazy cycle fix` (Spring Boot 4 production behaviour) ## Acceptance criteria - [ ] `docs/DEPLOYMENT.md` exists. - [ ] **Behavioural test (per Elicit)**: a developer who has never run the system can follow DOC-5 alone to bring the production stack to a healthy state on a fresh VPS. - [ ] "Secrets checklist" lists every must-set env var with **fail-fast vs dev-default** classification. - [ ] Every operational section either contains the content or links to the canonical infrastructure doc — no duplication. - [ ] Linked from `README.md`. - [ ] Rubric C9.1, C9.2 PASS verified by reviewer. ## Definition of Done DEPLOYMENT.md is on `main`. Behavioural test passes (verifiable by handing the doc to someone unfamiliar with the stack). Rubric C9.1, C9.2 PASS.
marcel added this to the (deleted) milestone 2026-05-05 21:08:15 +02:00
marcel added the P1-highdocumentationlegibility labels 2026-05-05 21:08:22 +02:00
marcel commented 2026-05-05 21:14:21 +02:00
Author
Owner
Copy Link

Duplicate of #399. I created this in error before noticing #399 already existed. #399 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.

**Duplicate of #399.** I created this in error before noticing #399 already existed. #399 carries the persona reviews and per-child Decision Queue; closing this in favor of the existing issue.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.
 P1-high
Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.
 P2-medium
Noticeable improvement; doesn't block anything; schedule opportunistically.
 P3-later
Cosmetic or parking-lot work; fine to stay open indefinitely.
 audit
Read-only audit / assessment work; produces a report rather than changing code
 bug
Something isn't working
 cleanup
Removal of dead code, vague comments, naming violations, and scratch artifacts
 collaboration
We want to extend the family archive to have more collaboration tools
 conversation
descoped
We will do that later
 devops
documentation
README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs
 epic
Marker for epic-level issues that group multiple child issues
 feature
file-upload
legibility
Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction
 notification
person
phase-1: security
Security hygiene — must be done first
 phase-2: container-images
Production-ready multi-stage Docker images
 phase-3: prod-compose
Production compose overlay + Caddy reverse proxy
 phase-4: spring-prod-profile
Spring Boot production configuration profile
 phase-5: backups
Database and object storage backup strategy
 phase-6: deployment-docs
.env.example, DEPLOYMENT.md, runbook
 phase-7: monitoring
Prometheus, Loki, Grafana, Alertmanager
 refactor
Code restructuring without behaviour change
 security
test
ui
UI/UX and accessibility issues
 user
No Label P1-high documentation legibility
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Jens marcel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: marcel/familienarchiv#436
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?