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

Intended architecture: build tools execute before serving; Caddy remains the web server. Browser CSP is separate. Publish only generated files: the root is not a symlink sandbox.

Context

The site is documentation and operations content: pages to be read, searched, and archived. A dynamic application server could render templates, manage sessions, or serve interactive components, but those are capabilities rather than current requirements. 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, an immutable release directory selected through a controlled publication switch. The directory-release ADR explains the switch and its cross-request limits. No application server, scripting lane, or database lives behind the edge.

Browser ──HTTPS──► Caddy ──filesystem reads──► public/ release tree

The intended no-script browser contract is delivered through headers (script-src 'none') and supported by build-time checks that reject executable scripts and broken artifacts. CSP is enforced by the browser; it does not prove the absence of an application server. The build output is public/, which includes generated pages and files copied from the source static/ directory.

Consequences

Releases are simpler: the content artifact has no application state or database schema to migrate. Publication, cache behavior, and rollback still need verification.
The threat surface is narrower: there is no application template evaluator or database query layer on the request path. Caddy and the browser still parse untrusted input, and the generator and dependencies still execute during builds.
Caching is inspectable: immutable release files have stable bytes. Validators, compression variants, and freshness directives still need correct server configuration.
Trade-offs accepted: no script-driven interactivity, authenticated personalization, or per-user HTML. Native document interactions remain available. Where that is genuinely needed, it would compose behind a separate service rather than be folded into this tree.

Boundaries that remain

Publish only the generated tree, not the repository root, build credentials, or private content. Caddy’s root is not a filesystem sandbox: a symlink inside it can expose a target outside that root. Review artifact symlinks, permissions, and error routes before publication. A no-script CSP does not make HTML injection harmless or protect an exposed secret file.

Keep the server patched, validate the actual public response, and retain a tested previous release. These are continuing operational responsibilities, even though the application tier was removed. The repository documents the intended architecture and sample configuration; it is not an inventory proving the present production host has no other services.

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-10-15.
MDN: Content Security Policy, browser resource and execution policy, checked 2026-10-15.

Pin the vendored theme and the generator version

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

Pins narrow drift. Compare controlled builds and keep the inputs with the result; the recorded four-build match has a specific historical scope.

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. A release manifest identifies one artifact. Reproducing it is a stronger claim: source, environment, and instructions must be controlled well enough to generate identical bytes again.

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 make build target checks the installed Hugo version against .hugo_version; make check-upstream, also invoked separately by CI, cross-checks that version with the TOML pin and the PaperMod release recorded in THIRD_PARTY_NOTICES.md. The latter checks recorded consistency, not a fresh comparison of every vendored file with upstream.

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

Controlled inputs: pinning removes two sources of drift. It does not alone prove identical output.
Visible upgrades: updating the generator pin or vendored theme bytes is an explicit reviewable change. Theme modifications remain visible in Git even if the release label is unchanged.
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.

Reproducibility still needs a test

The current Makefile writes the current UTC time into data/buildinfo.toml on each build. That timestamp is rendered in the site, so two normal builds at different times are intentionally not byte-identical. A commit label also does not describe uncommitted edits. Record a clean source revision and the exact build metadata alongside the artifact.

To test deterministic rendering, work in an isolated checkout, fix the same build metadata, toolchain, configuration, environment, and asset inputs, then invoke Hugo twice into separate empty destinations. Generate sorted path-to-SHA-256 manifests for both outputs and compare them. Keep the chosen inputs with the result. Do not claim that SOURCE_DATE_EPOCH is honored by this Makefile: it explicitly calls date.

An earlier complete-site two-build check with fixed build metadata produced 4,695 files in each output and 165 differing paths, including taxonomy display casing such as HTTP versus Http. That failed result remains part of the history; the version pins alone did not establish deterministic output.

The original report describes a later isolated Linux check that fixed the same build metadata and Hugo clock, then compared four complete builds before and four after a content-only taxonomy change. The change adds explicit term metadata for the 28 language/term case collisions, corrects the Chinese nginx tag to 漏桶, and preserves its historical /zh/tags/令牌桶/ URL. All four patched outputs contained 4,695 files and had identical sorted path-to-SHA-256 manifests; every published path, tag member sequence, pagination target, and XML route was retained, with no build warnings. The reported conclusion concerns repeatability only for that source snapshot, Hugo 0.165.0 Extended, vendored theme and Linux environment. It does not establish cross-platform, cross-year, future-version or future-content reproducibility. Re-run the comparison after changing those inputs, and do not use two ordinary make build invocations as a fixed-metadata test.

The recovered article and diagram retain that historical report, but the recovered materials do not include the original run logs or comparison manifests for the later four-build result. It has not been independently reproduced in this review. The later recovery of taxonomy title metadata is a separate exercise and does not supply the missing evidence for the original experiment.

Version pins are not permanent approval to run old software. Review upstream fixes, assess their relevance, update the recorded versions and vendored bytes together where appropriate, then run the full verification and inspect the generated diff.

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 narrows the investigation when the build changes; timestamps, content, configuration, and environment remain possible causes. That is a useful boundary without overstating reproducibility.

Sources

Reproducible Builds: definitions, controlled inputs and bit-for-bit comparison, checked 2026-10-15.
Hugo command reference, explicit build destinations and configuration options, checked 2026-10-15.
Hugo documentation: version, reporting and matching the generator release, checked 2026-10-15.
Semantic Versioning specification, version labeling conventions, not a reproducibility guarantee, checked 2026-10-15.

Publish complete release trees through an atomic pointer

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

A same-filesystem symlink replacement selects complete trees. Old asset URLs must remain reachable. This local pattern does not prove production migration, browser-wide transactions, automatic rollback, or power-loss durability.

Context

Copying changed files over a live tree exposes partial releases and makes the previous version difficult to name. Complete staging solves the partial-copy problem, but “rename the new directory over the old one” is not a sufficient publication procedure. mv new existing-directory normally moves new inside the destination. A plain POSIX rename cannot replace an existing non-empty directory. Renaming the old directory away and then the new one into place leaves a gap between two operations.

Decision

Keep immutable, versioned release directories and select one through a current symlink. Configure the file server to serve that stable path. After checking a new tree, create a temporary symlink beside current and atomically replace the symlink itself using a same-filesystem rename. The old release directory remains untouched under its versioned name.

This is the implementation pattern for the complete-tree decision, not evidence that a production host has already been migrated to it. An existing real-directory serve root requires a separately planned migration. Never run the example against that path and assume a symlink will replace it safely.

Rehearse the switch and rollback locally

The following Python 3 exercise creates only disposable local files. It demonstrates the pointer operation on a POSIX filesystem, without starting Caddy or changing a deployment.

from pathlib import Path
from tempfile import TemporaryDirectory
import os

with TemporaryDirectory() as tmp:
 root = Path(tmp)
 for version in ("v1", "v2"):
 release = root / "releases" / version
 release.mkdir(parents=True)
 (release / "index.html").write_text(version, encoding="utf-8")
 current = root / "current"
 current.symlink_to("releases/v1", target_is_directory=True)
 previous = os.readlink(current)
 with (current / "index.html").open() as in_flight:
 pending = root / "current.next"
 pending.symlink_to("releases/v2", target_is_directory=True)
 os.replace(pending, current)
 print("new open:", (current / "index.html").read_text())
 print("already open:", in_flight.read())
 pending.symlink_to(previous, target_is_directory=True)
 os.replace(pending, current)
 print("rollback:", (current / "index.html").read_text())

Expected output is new open: v2, already open: v1, and rollback: v1. The successful rename makes the directory entry replacement atomic. It does not change a file descriptor already opened on the old file, and it does not test power-loss durability or HTTP routing.

Consequences

No half-copied live tree: each release is complete before selection. Never mutate a selected or retained release directory.
Named rollback: replace current with a fresh temporary symlink to the recorded previous target. Rollback is an action to perform and verify, not something a failed smoke test does automatically.
Preflight evidence: check the staged manifest, file ownership, readable permissions, and available space before switching. Keep the manifest outside the hashed tree.
Serialized publishers: allow one deployment at a time. A fixed temporary link name is safe in this isolated exercise; production needs coordination and a collision-safe pending name.
Storage trade-off: retain previous releases long enough for rollback and in-flight clients; prune only after the retention window and checks.

Atomic pointer replacement is not a transaction spanning a browser page and all its asset requests. A browser can receive old HTML before the switch and request assets afterward. Fingerprinted asset URLs help only if the old asset bytes remain reachable at those URLs from the new served tree or a retained asset store. Merely keeping the old release directory elsewhere on disk is insufficient. Caches can also retain old responses after either publication or rollback.

The temporary link and current must be on the same filesystem; their common parent is a convenient way to ensure this. Check the filesystem and server’s actual symlink behavior. Rename atomicity concerns concurrent visibility, not survival after a sudden power loss; stronger durability needs file/directory synchronization appropriate to the filesystem. The served root is not a sandbox, so reject unintended symlinks within release content.

Why this beats in-place sync

The release can be named, verified before exposure, selected in one pointer operation, and restored from a known target. Those are useful guarantees without promising a globally instantaneous update, cross-request snapshot isolation, or automatic recovery after every failure.

Sources

Linux man-pages: rename(2), atomic replacement, non-empty directories, symlinks, and open descriptors, checked 2026-10-15.
Python os.replace, atomic successful replacement and non-empty-directory/cross-filesystem limits, checked 2026-10-15.
Caddy file_server, root resolution and symlink security boundaries, checked 2026-10-15.