docs: add APT/DNF Worker learnings + CLAUDE.md Distribution section#512
Merged
docs: add APT/DNF Worker learnings + CLAUDE.md Distribution section#512
Conversation
Phase 5 docs follow-up to #493. The plan doc was deleted in #511; this replaces it with a learnings file aimed at future maintainers (and future-me) rather than a design spec. docs/learnings/apt-worker-architecture.md covers: - The problem (100MB push cap) and why other fixes were rejected - Redirect chains for both legacy github.io users and direct pkg.<domain> users - Why raw.githubusercontent.com is the origin (Pages 301 loop) - Why Pages emits http:// (no cert, and why the cert can't be had) - File map (worker source, wrangler.toml, deploy workflow, heartbeat) - Credential ownership (Cloudflare account, registrar, API token scopes) - Heartbeat failure runbook — 5 ordered steps to work through - Rollback paths and documented fallbacks if Cloudflare becomes unavailable - Known gotchas including the smoke-test-URL-is-intentionally-github.io note so future cleanup passes don't "fix" it CLAUDE.md gains: - Link to the new learnings file in the Learnings list - New "Distribution" section under CI/CD with a one-paragraph summary and pointers to the key files Refs #493
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
Phase 5 docs follow-up to #493. The plan doc was retired in #511 once the implementation shipped; this replaces it with a learnings file aimed at future maintainers (and future-me in a year) rather than a forward-looking design spec.
What's in the learnings file
docs/learnings/apt-worker-architecture.md— one file a future maintainer can open cold and recover from an outage or credential rotation. Covers:aaddrick.github.iousers, one for directpkg.<domain>users — with the exact hostnames each hop lands onraw.githubusercontent.comis the Worker's origin, notaaddrick.github.io(Pages 301 loop risk that bit me during cutover)http://in its redirect (no cert, because DNS points at Cloudflare; Pages can't ever verify) and why that's the apt-breaks-but-dnf-works root causeheartbeat-failure-deborheartbeat-failure-rpmauto-opens a tracking issueWhat's in CLAUDE.md
## Distributionsection under## CI/CDwith a one-paragraph summary, the key file paths, the repo-secret names, and a pointer to the learnings fileNot in scope
worker/.wrangler/→.gitignore(separate minor cleanup)Refs #493
Generated with Claude Code
Co-Authored-By: Claude Opus 4.7 [email protected]