Decisions · XB Field Notes

The site is served as a static tree, not by a dynamic application server

Tue, 25 Aug 2026 00:00:00 +0000

Context

The site is documentation and operations content: pages to be read, searched, and archived. Early brainstorming considered a dynamic application server to render templates, manage sessions, or serve interactive components. The content itself imposes no requirement for server-side state, authenticated per-user logic, or client-side rendering.

Decision

Serve the site as a pre-built static tree from Caddy, a single directory that is swapped as a whole on release. No application server, scripting lane, or database lives behind the edge.

Caddy (public edge) ──HTTPS──► static/ tree (assets, HTML, SVGs)

The served contract is enforced by headers (script-src 'none') and by build-time checks that reject scripts and broken artifacts.

Consequences

Releases are boring: publishing is a complete-directory swap, so there is no state migration and no schema.
The threat surface is narrow: no runtime executes user input, closing whole injection classes.
Caching is honest: every file has a stable byte identity and a validator.
Trade-offs accepted: no interactivity, no authenticated personalization, no per-user HTML. Where that is genuinely needed, it would compose behind a separate service rather than be folded into this tree.

Why this beats the alternative

A dynamic tier adds a runtime, a state boundary, and a slower path to edit. For content whose value is in the document itself, that cost buys capabilities the content does not use. Static serving gives away nothing the site needs and removes the parts that would only complicate releases and the security boundary.

Sources

Caddy documentation: file_server, serving a static root without an application tier, checked 2026-08-25.
MDN: Content Security Policy, restricting what the edge will execute, checked 2026-08-25.

Pin the vendored theme and the generator version

Fri, 21 Aug 2026 00:00:00 +0000

Context

The site is built with a Hugo generator and a PaperMod theme. Untracked upgrades of either can change output silently: the theme’s templates, the generator’s rendering rules, or both can alter the HTML bytes between two “identical” rebuilds. When a release is proven by a byte manifest, reproducibility is not a nice-to-have; two builds of the same source must produce the same tree.

Decision

Vendor the theme into the repository and record the exact generator version and theme version in a pin file, data/upstream-pins.toml. The build pipeline reads that file and fails if the installed generator does not match the pinned version.

Hugo 0.165.0
PaperMod v8.0
data/upstream-pins.toml (pinned)

Themes that are vendored stay under themes/ in the tree so they are part of the commit and therefore part of the byte identity of a release.

Consequences

Reproducible output: the same source plus the pinned generator yields the same tree, so the manifest means something.
Visible upgrades: bumping the theme or generator is an explicit, reviewable change to the pin file, not an accidental drift.
Auditable provenance: a reader of any release can see which generator and theme produced the bytes.
Trade-off accepted: the repository carries the vendored theme and the pin bookkeeping; the cost is small against silent output drift.

Why this wins

A build whose inputs are not pinned can produce the right answer today and a different tree tomorrow, and neither the diff nor the manifest can tell you why. Pinning turns “the build changed” into “the pin changed”, which is a question a changelog can actually answer.

Sources

Hugo documentation: version, reporting and matching the generator release, checked 2026-08-21.
Semantic Versioning specification, why version boundaries make reproducibility meaningful, checked 2026-08-21.

Publish by exchanging complete directories, never file-by-file

Thu, 20 Aug 2026 00:00:00 +0000

Context

Deploying by copying changed files over a live tree risks a window where visitors see a partial release: some files are new, others old, and associated resources disagree. A malformed single file can also corrupt an otherwise fine live site. Any release path that edits the served directory in place makes the “previous release” difficult to name and restore.

Decision

Publish by staging a complete new tree beside the live tree, then renaming the single directory Caddy serves to point at it. The old tree remains on disk under its prior name.

rsync -a public/ /srv/www/example-site.new/
mv /srv/www/example-site.new /srv/www/example-site

Because the serve root is one directory name, the swap is atomic from the client’s perspective: every request resolves to either the old complete tree or the new complete tree, never a mix.

Consequences

No partial states: a visitor always sees one coherent release.
Cheap rollback: the old tree still exists; recovery is a reverse rename.
Verifiable before swap: the staged tree can be checked and hashed before it becomes the served one.
Storage trade-off: the server holds the current tree plus a staged tree; the extra disk is the price of atomicity.

Why this beats in-place sync

In-place sync promises to adjust a live tree, but it cannot answer the question “which bytes are being served right now” atomically, and it complicates rollback to “yesterday”. Complete-directory exchange answers the release question with one durable fact — the served directory name — and makes both forward and backward moves a single rename.

Sources

Martin Fowler: BlueGreenDeployment, complete-tree versus blue-green/staged exchange models, checked 2026-08-20.
POSIX rename(), atomic rename semantics underpinning the swap, checked 2026-08-20.