docs(deployment): rewrite as a four-step path, not a tour of design choices - #58
Merged
Conversation
…hoices
The old page led with "Design choices", "Mental model", and a SignalGrid
before getting to the actual prep work. Operators don't want a tour;
they want to follow numbered steps to a working site.
New shape — four numbered sections, then day-2 / rollback / related:
1. Accounts (Cloudflare, Hetzner, GitHub, 1Password) as a 4-row table
2. Secrets into 1Password — generate locally, mint provider tokens,
stash everything in a "Production" vault with a concrete layout
3. Provision via OpenTofu (a) OR manual (b)
4. Verify with three concrete curls
The opinionated bits are stated, not philosophised. 1Password is the
canonical recommendation (alternatives mentioned in one line); the
vault layout is shown; CLI snippet for the random-string items.
MFA_ENCRYPTION_KEY's non-rotatable nature gets a callout where it
matters (during generation), not buried in a "guardrails" FAQ.
What got cut from this page (still available, just elsewhere):
- "Design choices" FAQ → already covered in /architecture/decisions/
- "Boot-time guardrails" FAQ → the validator emits its own errors;
the page doesn't need to pre-enumerate them
- "Image update strategy" → links to existing /runbooks/image-updates/
- "Provider notes" → links to /topics/provisioning-with-tofu/
- "Where to scale up" → out of scope for first deploy
Total: 302 → 188 lines (-38%). Build clean, no broken links.
agjs
enabled auto-merge (squash)
May 30, 2026 09:57
agjs
disabled auto-merge
May 30, 2026 10:18
2 tasks
agjs
added a commit
that referenced
this pull request
May 30, 2026
…#59) `register → login → /me through the full stack` is a required check in branch protection on `main`. The smoke workflow had a `paths:` filter on its `pull_request:` trigger that excluded docs-only PRs entirely — so for docs PRs the workflow never ran, never reported a status, and branch protection blocked merge forever. PR #58 hit this and had to land via admin override. The job body already uses dorny/paths-filter and gates every real step on `if: steps.filter.outputs.code == 'true'`. So removing the trigger- level `paths:` doesn't waste runner time on docs PRs — they execute just the checkout + filter (~30s) and exit success with the required check name reported green. The expensive smoke loop (compose up, Playwright) only runs when code paths actually change. Keeping the `push:` paths filter as-is: we don't want every docs commit on main to fire the smoke loop.
3 tasks
agjs
added a commit
that referenced
this pull request
May 30, 2026
…Rs (#61) dorny/paths-filter standalone negation patterns (`'!apps/api/**/*.md'` and the like) don't behave like exclude-from-include rules — they evaluate to true for ANY changed file that doesn't fit the inverse pattern. Net effect: on a docs-only PR with no code touched, the `code` filter still returned `true` because a docs `.mdx` file doesn't match `apps/api/**/*.md`, so the negation "matched". Concrete evidence: PR #58 (only changed `apps/docs/.../deployment.mdx`). Every step in `apps-api-ci.yml`'s `validate` job ran — checkout, filter, Bun, install, db migrations, full test suite, coverage, production bundle. The buggy negation set `Filter code = true`, the internal `if: steps.filter.outputs.code == 'true'` gates all short-circuited to "run", and we hit a unit-test flake on a PR that touched zero application code. Removed the negation lines from all 10 affected workflows. The filter now matches strictly on the positive paths (`apps/api/**`, `apps/ui/**`, etc. + the workflow file itself). Trade-off: a `README.md` change inside `apps/api/` will now trigger api-ci. That's acceptable — those changes are rare, and the previous "fast-skip" optimisation wasn't actually working anyway. Net effect on docs-only PRs: api-ci, ui-validate, smoke, bootstrap-validate, validate-compose, and the security workflows all now correctly skip-with-success in ~30 s instead of running their full pipelines. Files touched (10 workflows, 22 lines deleted): apps-api-ci.yml apps-api-security-{deps,sast,secrets}.yml apps-ui-security-{deps,sast,secrets}.yml apps-ui-validate.yml infra-bootstrap-validate.yml infra-compose-full-stack-smoke.yml infra-compose-validate-compose.yml (3 filter blocks) This PR self-verifies: it's workflow-only, so the `code` filter on every affected workflow should now correctly evaluate to `false` on this PR (no apps/api, apps/ui, infra/* changes), and the heavy jobs should report quick green via skip-with-success. If you see Bun install + full test suite running on this PR, the fix is wrong.
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.
Summary
Old page led with "Design choices", "Mental model", and a SignalGrid before the actual steps. Operators don't read novels — they scan for the path to a working site.
New shape — four numbered steps, then day-2 / rollback / related:
Then: day-2 deploys, rollback, related.
Cut (still available elsewhere, linked):
302 → 188 lines (-38%).
Test plan