docs(tofu): close end-to-end gaps so a fresh apply works from the docs - #57
Merged
Conversation
A real run against the provisioning-with-tofu doc surfaced four gaps:
1. terraform.tfvars.example was missing slots for ghcr_username,
ghcr_token, superuser_email, and superuser_password — all declared
in variables.tf and wired through main.tf, but invisible to an
operator following the docs.
2. LinkedIn OAuth was half-wired: the API has a full LinkedIn provider
(apps/api/src/lib/oauth/providers/linkedin.ts) and apps/api/.env.example
exposes LINKEDIN_OAUTH_CLIENT_{ID,SECRET}, but the tofu side was
missing — no variable declarations, no module wiring, no template
rendering. tfvars.example had commented entries that would emit
"undeclared variable" warnings if uncommented. Wired through the
same pattern as Google/GitHub (root variables.tf → bootstrap module
variables.tf → main.tf passthrough → compose.env.tftpl render).
3. PageIntro said "configures Cloudflare DNS firewalls" — reads like
Cloudflare's paid DNS Firewall product. Tweaked to "Cloudflare DNS
and a Hetzner firewall scoped to Cloudflare's IP ranges".
4. Sample output claimed "Resources: 5 added" — actual count is 9
(server, SSH key, firewall, apex A/AAAA, www CNAME, two zone
settings, redirect ruleset).
Two pieces of operator guidance also added:
- `cloud-init status: done` only means cloud-init's own steps ran —
it doesn't reflect bootstrap.sh failures inside the script. Added a
callout pointing at /var/log/cloud-init-output.log + the right
docker compose commands to find the actual problem.
- "Site returns 525" on first apply is normal for 2–5 minutes while
DNS propagates and ACME issues the first cert. Expanded the
troubleshooting entry to set expectations + suggest the dig +
Traefik log commands operators actually need.
Also fixed a stray empty description on github_oauth_client_secret.
tofu fmt + validate clean. Docs build clean (67 pages).
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
Fixes four blocking gaps an operator would hit when following `provisioning-with-tofu.mdx` end-to-end against a fresh Hetzner project, plus two pieces of operator guidance.
Required vars now in `terraform.tfvars.example` — `ghcr_username`, `ghcr_token`, `superuser_email`, `superuser_password`. All were declared in `variables.tf` and wired through `main.tf`, but invisible from the example file.
LinkedIn OAuth wired through tofu. API has a full LinkedIn provider; `apps/api/.env.example` exposes `LINKEDIN_OAUTH_CLIENT_{ID,SECRET}`; `tfvars.example` had commented LinkedIn entries that would emit "undeclared variable" warnings if uncommented. Now follows the same path as Google/GitHub: root variables.tf → bootstrap module variables.tf → main.tf passthrough → compose.env.tftpl.
Wording fixes: `configures Cloudflare DNS firewalls` → `Cloudflare DNS and a Hetzner firewall scoped to Cloudflare's IP ranges`. Sample apply output `5 added` → `9 added` to match the real count.
New troubleshooting callouts:
Bonus: filled an empty description on `github_oauth_client_secret`.
Test plan