docs(identity): condense the migration plan and the stale Caddy steps - #408
Merged
Conversation
authentik-migration.md had grown to 1646 lines because every finished stage kept both its original plan text and a "what actually happened" correction on top of it, and most of that correction is already written up as procedure in identity/README.md. Reading it to answer "what is left" meant reading all of it. Restructured around what is still to do. A status table up front says which stage is where; finished stages keep their outcome and only the lessons that are rules for future work; the remaining stages (6e's sitting, 6f-pre, 6f) keep their full detail. Per-app OIDC values, break-glass and rollback commands are no longer repeated here, since identity/README.md carries them in more depth and one of the two copies was always going to drift. Nothing durable is dropped. The decision numbering is unchanged, because compose.yaml, the blueprints, site.yml.example, the Ansible contract and three tests all cite decisions 6, 8 and 9 by number. Two facts that only lived in the stage narratives are now stated where they act: the Postgres major pin sits with the rest of decision 2, and the local password hash that authentik's recovery flow leaves behind is an open question for 6f rather than a footnote under a pre-flight check. landing-page.md section 4 still explained how to hand-edit the Caddyfile, which SITE-7 has rendered since PR #394, and then said not to. Cut to what the template renders and why (the XFP pin, the no-store header, /whoami and its three limits) plus the staged validate-and-reload order. 1646 -> 745 lines and 583 -> 543.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs/authentik-migration.mdgoes from 1646 to 745 lines,docs/landing-page.mdfrom 583 to 543. Docs only, no code, no behaviour change.Why
The migration plan had accreted a "what actually happened" correction on top of the original plan text for every finished stage, and most of that correction is already written up as usable procedure in
identity/README.md. Answering "what is left before 6f" meant reading all 1646 lines, and the two copies of the per-app detail were going to drift.What changed
!Envcontainer-passthrough trap).identity/README.mdis named as the place for them.Decision numbering is unchanged.
identity/compose.yaml, three blueprints,site.yml.example,docs/ansible/behavior-contract.md,web/caddy/Caddyfile.j2and two tests cite decisions 6, 8 and 9 by number.Two facts that only lived inside a stage narrative are now stated where they act:
18.x-alpinemajor pin sits with the rest of decision 2;docs/landing-page.mdsection 4 still explained how to hand-edit the Caddyfile, which SITE-7 has rendered since #394, and then said not to. Cut to what the template renders and why (theX-Forwarded-Protopin,Cache-Control: private, no-store,/whoamiand its three limits) plus the staged validate-then-reload order.Checks
bash tests/run.sh- all suites pass, no failures.bash tests/test-opsec.sh- passed=7 failed=0 (no public FQDN reached a tracked file).mkdocs build --strict- clean.pre-commit run --files docs/authentik-migration.md docs/landing-page.md- passed.