Release · XB Field Notes

Hugo publication flags decide what enters the artifact

Sat, 18 Mar 2028 00:00:00 +0000

Hugo decides which pages to render when a build runs. Front matter supplies publication metadata, configuration and command flags supply inclusion rules, and the build clock supplies the time used for evaluation. The deployed directory then stays unchanged until another artifact replaces it. A date reaching midnight is not itself a deployment event, and a file without draft: true is not automatically a draft.

Separate publication metadata from build options

Under the default rules, a page marked draft: true is excluded. A future publication date also excludes it, while an expired page is excluded after its expiry date. Hugo resolves dates according to its front matter configuration; an explicit publishDate can differ from the displayed date. Use complete timestamps with a time zone for a boundary that must mean the same thing on a laptop and a build worker.

--buildDrafts includes drafts, --buildFuture includes future content, and --buildExpired includes expired content. Their short forms are -D, -F, and -E. These switches address separate conditions: a future draft needs both draft and future inclusion before the date arrives. Project or environment configuration can enable the same behavior, so checking only a page’s front matter is insufficient.

This site’s configuration deliberately enables buildFuture: true to retain its published article inventory, including articles dated in the future. Consequently, those dates are not an embargo here. A tutorial about Hugo defaults must not be mistaken for a claim about this site’s active settings. Compare the effective options with the expected URL inventory before changing publication policy.

A preview artifact can still be published

A preview flag changes the generated output, not its sensitivity or deployability. If a pipeline uploads a directory built with -D -F, those pages can become public. Use a separate destination for preview builds and construct the release artifact with the intended options. A Git release tag identifies source history; it neither changes Hugo’s inclusion rules nor certifies that a particular generated directory was reviewed.

Scheduled publication requires a later build and deployment after the publication boundary. Conversely, changing a public page back to draft cannot withdraw HTML that is already deployed or cached. Rebuild, replace the served artifact, and inspect the public route. Hugo normally leaves unrelated files in an existing destination, so a fresh output directory or an appropriate clean build is part of verifying that excluded pages are absent.

When it breaks

A preview build copied over a release directory can leave a draft accessible by its direct URL even after the navigation no longer lists it. Inspect generated files, feeds, sitemaps, and the actual served route; hiding an index entry is not removal. A draft section page also does not automatically make all descendants drafts. Use explicit child metadata or the documented cascade mechanism when exclusion must apply to a subtree.

Time-zone mismatches cause a different failure: two workers include different pages from the same commit. Pin the generator, use an explicit build clock for boundary tests, and record the options. Do not repair the discrepancy by changing publication dates until the date resolution rules and worker time zones are understood.

Hugo inclusion gates: mechanism and evidence boundaries.

Check it quickly

With Python 3 and Hugo 0.165.0 available, this isolated experiment creates five pages and eight fresh build destinations. Run Python with assertions enabled: omit -O and unset PYTHONOPTIMIZE. It neither changes this repository nor deploys anything. This source review did not execute it.

from pathlib import Path
from tempfile import TemporaryDirectory
import subprocess

with TemporaryDirectory(prefix="hugo-publication-") as directory:
 root = Path(directory)
 (root / "content/posts").mkdir(parents=True)
 (root / "layouts/_default").mkdir(parents=True)
 (root / "hugo.yaml").write_text("baseURL: https://example.org/\n")
 (root / "layouts/index.html").write_text("<h1>Publication test</h1>")
 (root / "layouts/_default/list.html").write_text("{{ .Title }}")
 (root / "layouts/_default/single.html").write_text("{{ .Title }}")
 for name, extra in {
 "visible": "",
 "draft": "draft: true\n",
 "future": "publishDate: 2030-01-01T00:00:00Z\n",
 "future-draft": "draft: true\npublishDate: 2030-01-01T00:00:00Z\n",
 "expired": "expiryDate: 2025-12-01T00:00:00Z\n",
 }.items():
 (root / f"content/posts/{name}.md").write_text(
 f"---\ntitle: {name}\ndate: 2025-01-01T00:00:00Z\n"
 + extra + "---\nPublication fixture.\n"
 )
 cases = [
 ("normal", "2026", [], {"visible"}),
 ("drafts", "2026", ["-D"], {"visible", "draft"}),
 ("future", "2026", ["-F"], {"visible", "future"}),
 ("preview", "2026", ["-D", "-F"], {"visible", "draft", "future", "future-draft"}),
 ("expired", "2026", ["-E"], {"visible", "expired"}),
 ("all", "2026", ["-D", "-F", "-E"], {"visible", "draft", "future", "future-draft", "expired"}),
 ("boundary", "2030", [], {"visible", "future"}),
 ("later", "2031", [], {"visible", "future"}),
 ]
 for name, year, flags, expected in cases:
 destination = root / f"output-{name}"
 subprocess.run(
 ["hugo", "--source", str(root), "--destination", str(destination),
 "--clock", year + "-01-01T00:00:00Z", *flags],
 check=True, capture_output=True, text=True,
 )
 actual = {p.parent.name for p in destination.glob("posts/*/index.html")}
 assert actual == expected, (name, actual, expected)
 print(name, sorted(actual))

The assertions verify default exclusion, each inclusion flag, their combination, and publication at and after the boundary. Both drafts remain absent from later normal builds. A future draft appears early only with both -D and -F, while -E independently includes the expired page. This checks Hugo’s rendering decisions under controlled inputs; it does not test the deployment scheduler, CDN invalidation, or this site’s future-inclusive configuration. Those need separate artifact and public-route evidence at release time.

Keep these cases when changing publication options: ordinary, future, draft, future-draft, and expired pages exercise different inclusion conditions. Check newly generated files rather than assuming that missing navigation links prove exclusion.

Sources

Hugo: Basic usage, draft, future, expired content, and destination behavior, checked 2026-09-06.
Hugo: Front matter, publication metadata and cascading settings, checked 2026-09-06.
Hugo command reference, inclusion switches and the build clock, checked 2026-09-06.
Python assert statement, optimization removes assertions and their expressions, checked 2026-10-18.

Git tags pin a release to a commit

Fri, 11 Jun 2027 00:00:00 +0000

A release tag gives people a readable name for a particular source revision. Unlike a branch, it does not advance when another commit is created. However, Git does not make a tag reference physically impossible to change: a user with sufficient access can replace or delete it. The dependable release contract is therefore a combination of a recorded object ID, an immutable-name policy, and controls over who may update release references.

A lightweight tag points straight to a commit; an annotated tag points through a separate tag object. Tags do not advance with new commits, but access controls and policy are needed to preserve release names. Signature trust, artifact provenance and remote distribution are separate checks.

Two kinds of tags

A lightweight tag is a reference directly naming an object, usually a commit. An annotated tag names a separate tag object containing a target, tagger identity, timestamp, message, and optionally a signature. The identity is the person making the tag, which need not be the commit’s author. An annotated tag is not automatically signed just because it contains this metadata.

For an annotated release, git rev-parse refs/tags/v2.4.1 identifies the tag object, while git rev-parse 'refs/tags/v2.4.1^{commit}' resolves its target commit. Record both when annotation or signature identity matters. Checking only the commit misses changes to the tag message or signer; checking only the readable name does not establish either identity.

Why sign a release

git tag -v verifies a signed tag using the configured signing backend and locally available trust information. A successful cryptographic check is useful only if the key is also one your release policy authorizes. A mathematically valid signature from an unknown person does not establish that the project’s maintainer approved the release.

A signed source tag also does not prove that a downloaded binary was built from that source. Artifact checksums, provenance, and the build process establish that separate relationship. Do not pipe verification through head and then trust the pipeline’s last exit status: truncating the display can conceal the verifier’s failure. Capture and enforce the verification command’s own result.

Move with care

Correcting an unpublished local tag is different from replacing one that consumers already fetched. Once distributed, prefer a new version name and document the withdrawn release. A security fix does not require rewriting the old tag; preserving the original reference makes affected deployments easier to identify. Server-side protection should reject unauthorized release-tag updates and deletions.

If an exceptional replacement is approved, publish the exact old and new object IDs and coordinate that single reference with consumers. A blanket forced fetch of every tag can overwrite unrelated local references and should not be routine repair advice. Consumers should never discover silently that two different commits were both presented as the same release.

When it breaks

A floating name such as latest can resolve differently between builds. Record the resolved commit with every artifact and deployment, even if a convenience name is displayed to humans. Reusing a name does not make two builds identical, and pinning a commit does not by itself freeze external dependencies or compiler versions.

Another failure is a release tag available only in one local clone. Ordinary branch pushes do not necessarily transfer it. --follow-tags concerns qualifying annotated tags reachable from the pushed commits, not every local tag. Verify the exact remote reference and its object ID with git ls-remote --tags; a substring match on the version name can accidentally accept another release. Remote visibility proves distribution, not build correctness or signature trust.

Check it quickly

Run this on a POSIX system with Python 3 and Git. It creates an isolated temporary repository, supplies an example identity, disables signing for the demonstration, and creates no remote. It never tags the surrounding project. Python removes the disposable repository afterward.

import os
import subprocess
import tempfile

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-tag-demo-") as directory:
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Tag Example",
 "-c", "user.email=tags@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false",
 "-c", "core.hooksPath=/dev/null", *args],
 cwd=directory, env=env, text=True, capture_output=True, check=check,
 )

 git("init", "-q")
 git("commit", "--allow-empty", "-qm", "first")
 first = git("rev-parse", "HEAD").stdout.strip()
 git("tag", "-a", "demo-v1", "-m", "example release")
 git("tag", "demo-bookmark")
 print("annotated:", git("cat-file", "-t", "demo-v1").stdout.strip())
 print("lightweight:", git("cat-file", "-t", "demo-bookmark").stdout.strip())
 git("commit", "--allow-empty", "-qm", "second")
 target = git("rev-parse", "demo-v1^{commit}").stdout.strip()
 print("tag-still-first:", target == first)
 print("head-moved:", git("rev-parse", "HEAD").stdout.strip() != first)
 duplicate = git("tag", "demo-v1", check=False)
 print("existing-name-refused:", duplicate.returncode != 0
 and git("rev-parse", "demo-v1^{commit}").stdout.strip() == first)
 verification = git("tag", "-v", "demo-v1", check=False)
 print("unsigned-rejected:", verification.returncode != 0)

Expect object types tag and commit, followed by four True results. A new commit advances the branch without moving the tag. Reusing the existing name without force fails and leaves its target unchanged; this local safeguard is distinct from server-side protection. An unsigned annotation fails signature verification. The exercise intentionally does not demonstrate a trusted signature or remote publication; those need the project’s authorized key policy and actual remote-reference checks.

Sources

git-tag reference, tag objects and the consequences of replacing a distributed tag, checked 2026-10-15.
Git tagging basics, lightweight and annotated tags plus sharing behavior, checked 2026-10-15.

Rolling updates replace pods in small waves

Mon, 07 Jun 2027 00:00:00 +0000

A rolling update is a controlled replacement, not a promise of uninterrupted service. Its useful property is that the controller can retain old replicas while introducing new ones. Whether users notice the change also depends on spare capacity, meaningful health checks, and shutdown behavior. This article tunes that process; the companion strategy article asks whether versions should overlap at all.

Ten plus two is a target of twelve; ten minus one is a planning budget of nine. Account separately for terminating Pods, stable readiness and real request behavior.

The surge and the gap

With ten desired replicas, maxSurge: 2 permits a rollout target of twelve, not eleven. maxUnavailable: 1 gives the controller an availability budget of nine. It is not a limit of one old Pod deleted per wave: several old replicas can be removed once sufficient replacements are available. Terminating Pods can remain and consume resources beyond the surge target, so twelve is not a hard count of every Pod or process.

Percentages need rounding: surge rounds upward, unavailable downward. For three replicas, the default 25% yields one surge and zero unavailable. Kubernetes 1.34.0 has a boundary exception: zero surge plus a nonzero unavailable percentage that rounds to zero resolves to one unavailable replica, so replacement can progress. Do not infer a zero-disruption policy from that rounded zero.

Neither knob reserves resources. Compare requests with schedulable capacity, quota, placement constraints, and the shutdown tail before choosing faster replacement. A budget that looks affordable on paper may still leave every new Pod Pending.

Health gates replacement

Check that a readiness probe is actually configured. Readiness should answer whether this instance can serve its intended traffic. A listening port alone may miss application failure; checking a required backend can help, but a shared dependency failure can also withdraw every replica. Design that response deliberately rather than blindly weakening a failing probe.

minReadySeconds adds a stable-ready interval before a new Pod counts as available. It does not delay Service traffic until that interval finishes. A startup probe can protect slow initialization from premature liveness restarts. None of these checks proves correct business behavior or sustained throughput.

Shutdown needs its own test. Endpoint changes, connection draining, application signal handling, and the termination grace period must work together. A green readiness endpoint cannot prevent an application from dropping an in-flight request when it exits.

Choose a deliberate pace

One surge and zero unavailable is a useful starting point for a small fleet with spare capacity; it prevents intentional availability reduction by the rollout, not node failures or request errors. A PodDisruptionBudget does not constrain a Deployment’s own rolling upgrade.

Manual pause is useful for inspection, but it does not reserve an exact one-Pod canary or a fixed traffic percentage: reconciliation may advance before the pause takes effect. Use separately controlled canary capacity and routing when that exposure limit matters. Define error-rate, latency, restart, and business-check thresholds before starting, with an observation period after completion.

When it breaks

A stuck rollout needs evidence from the failing layer. Scheduling events point to capacity or placement; image-pull events point to registry access or image references; container logs and probe events distinguish crashes from readiness failures. Do not change probes until you know whether they are detecting a real fault.

A bad new version may consume the configured unavailable allowance before progress stalls. progressDeadlineSeconds reports stalled progress; it neither automatically rolls back nor freezes all reconciliation. Alert on the condition and decide whether to repair or revert. A completed rollout still needs a bake period for memory growth, connection exhaustion, and errors under realistic traffic. Retain usable revision history and the previous image through that period.

Check it quickly

Save this standard-library exercise as rounding_window.py and run python3 rounding_window.py. It checks percentage conversion using integer arithmetic, including a small fleet, an exact boundary, and 100%. It is not a Deployment controller simulation or a complete API validator. Its 0–100% input range is an exercise limit, not a maxSurge API restriction.

"""Check percentage rounding only; no Kubernetes API calls."""


def round_percent(replicas, percent, *, up):
 if type(replicas) is not int or replicas <= 0:
 raise ValueError("this exercise requires positive integer replicas")
 if type(percent) is not int or not 0 <= percent <= 100:
 raise ValueError("this exercise accepts integer percentages 0..100")
 numerator = replicas * percent
 return (numerator + 99) // 100 if up else numerator // 100


def main():
 cases = [(1, 1, 0, 1), (3, 25, 0, 1), (4, 50, 2, 2),
 (10, 20, 2, 2), (10, 10, 1, 1), (4, 100, 4, 4)]
 for replicas, percent, down, up in cases:
 assert round_percent(replicas, percent, up=False) == down
 assert round_percent(replicas, percent, up=True) == up
 print(f"replicas={replicas}, percent={percent}: down={down}, up={up}")
 print("PASS: percentage rounding only; no cluster exercised")


if __name__ == "__main__":
 main()

Expect six case lines and a final arithmetic-only PASS. Three replicas at 25% produce zero rounded down and one rounded up; ten at 20% produce two either way. The assertions were executed with Python 3.12.14 in Linux during this revision. They establish arithmetic, not service availability.

Before applying these numbers, select the intended test context and namespace and confirm the actual Deployment strategy. With an existing api Deployment and app=api Pods, kubectl rollout status deployment/api --timeout=120s observes convergence, while kubectl get pods -l app=api -w watches replacements in a separate terminal. A client timeout does not cancel the rollout. If releases overlap, use --revision=N to follow the intended revision. Stop the watch with Ctrl-C.

Those cluster commands were not executed here. Collect Pod events, logs, and Deployment status during a staging upgrade, together with continuous requests through the real Service or ingress. Record failures and latency during shutdown. This is the integration evidence still needed; a successful controller status alone cannot establish zero downtime.

Sources

Kubernetes Deployments, rollout budgets, readiness intervals, pause, and progress conditions, checked 2026-10-15.
Kubernetes probes, startup, liveness, and readiness responsibilities, checked 2026-10-15.
Kubernetes Pod lifecycle, termination and connection draining, checked 2026-10-15.
Kubernetes resource management, requests and scheduling capacity, checked 2026-10-15.
Kubernetes disruptions, limits of PodDisruptionBudgets during rolling upgrades, checked 2026-10-15.
kubectl reference, rollout status and timeout behavior, checked 2026-10-15.
Kubernetes controller rounding implementation, versioned ResolveFenceposts behavior when both rounded budgets are zero, checked 2026-10-15.

Blue-green deployment keeps two environments ready

Mon, 02 Nov 2026 00:00:00 +0000

Blue-green deployment prepares a new application version in a separate environment while the previous version serves traffic. After readiness checks, routing directs new work toward the new environment. Keeping the old environment available can shorten rollback, because recovery need not wait for another build. The pattern does not make every dependency duplicated, every switch instantaneous, or every data change reversible.

Routing selection and state compatibility are distinct. The model explains overlap and schema limits; it is not a measured router rollout or a guarantee of safe recovery.

Define what the switch controls

The routing mechanism might be a load-balancer backend, a service selector, or DNS. Each has different propagation and connection semantics. Updating one control-plane object does not imply that all data-plane instances change at the same instant. DNS caches and existing connections can continue using old destinations after the authoritative configuration changes.

Decide whether routing applies per request, connection, session, or queued job. A persistent connection can remain on blue while new connections reach green. Some proxies select an upstream for each request instead. The longest-lived client connection alone therefore does not define every drain window. Document the actual mechanism and its timeout and termination behavior.

Both versions should support their assigned traffic and dependencies. That does not require identical software versions or permanently paying exactly twice the total system cost. Capacity can be staged, and databases or supporting services may be shared. Savings have consequences: an old environment scaled down too far may no longer provide a quick, full-capacity rollback target.

Keep data compatible across the overlap

A shared database is common, but is a design choice rather than the definition of blue-green. Separate databases introduce replication, synchronization, and reconciliation questions. A routing reversal cannot erase writes already accepted by green or safely invent transactions missing from blue. Define what happens to data as carefully as what happens to requests.

With a shared store, expand-and-contract changes keep both versions working during overlap. Add compatible fields, deploy readers and writers that tolerate both representations, backfill where needed, and only later remove obsolete structure. Waiting for old HTTP connections to end is insufficient if old workers, scheduled jobs, rollback binaries, or external consumers still need the old schema.

Check semantic compatibility as well as column names. Both versions might parse a field while interpreting its units differently. A migration can cause rejected queries, inconsistent writes, or later corruption; corruption is not inevitable, but neither is a clean error. Exercise realistic read and write paths and validate representative business results before declaring rollback safe.

When it breaks

Mixed-version responses during cutover are not automatically a deployment failure. They may be the expected result of draining, gradual propagation, or intentional traffic splitting. They become a problem when clients or shared state cannot tolerate that overlap. Include release identity in useful diagnostics, then correlate failures with routing state, connection age, and application compatibility.

Conversely, fifty responses from one client all reporting green do not prove global atomicity. That client may repeatedly hit one edge or reuse one connection. Readiness replica counts also do not establish that a service selector, endpoint list, ingress controller, or external load balancer points at those replicas. Inspect the complete path and test representative client locations.

Finally, do not retire blue merely because the switch command succeeded. Define a rollback window, monitor error and latency changes, and confirm old workers have stopped before incompatible cleanup. If rollback depends on state that has already changed irreversibly, choose a forward repair or a rehearsed data-recovery procedure instead of repeatedly flipping the route.

Check it quickly

Run the following Python 3 model with assertions enabled. It changes only in-memory dictionaries. Two routers update separately, existing sessions retain their selected environment, and a schema contract determines whether either version can run. This is an explicit model, not a measured load-balancer rollout or a Kubernetes integration test.

routers = {"edge-a": "blue", "edge-b": "blue"}
existing = {"session-1": "blue", "session-2": "blue"}
routers["edge-a"] = "green"
assert set(routers.values()) == {"blue", "green"}
routers["edge-b"] = "green"
assert set(routers.values()) == {"green"}
assert set(existing.values()) == {"blue"}
print("new routes green; existing sessions still blue")

required = {"blue": {"amount_cents"}, "green": {"amount_cents", "currency"}}
def compatible(schema, colour):
 return required[colour] <= schema
schema = {"amount_cents", "currency"}
assert all(compatible(schema, colour) for colour in required)
routers = dict.fromkeys(routers, "blue")
assert compatible(schema, "blue")
print("rollback remains schema-compatible")

# A destructive replacement can invalidate the old version.
required["green"] = {"amount_minor", "currency"}
schema = {"amount_minor", "currency"}
assert compatible(schema, "green")
assert not compatible(schema, "blue")
print("routing rollback cannot restore a removed column")

The first assertion exposes a mixed routing state. Even after both routers select green, the modeled sessions remain blue. The additive schema supports a routing rollback; the later destructive replacement does not. The three output lines identify those boundaries without inventing a universal cutover duration.

Repeat these checks in an isolated deployment using the real router, representative traffic, and reversible test data. Measure propagation, draining, and rollback separately. Preserve evidence of both routing convergence and compatible application behavior; neither substitutes for the other.

Sources

Martin Fowler: Blue-Green Deployment, the original pattern write-up, including the shared-database caveat, checked 2026-09-16.
Kubernetes: Deployments, rollout, readiness and rollback semantics, checked 2026-09-16.
AWS: Blue/Green Deployments whitepaper, routing-level cutover and its costs, checked 2026-09-16.
AWS Route 53 cutover, DNS caching, weighted transitions and capacity tradeoffs, checked 2026-10-15.

Ship a static site and prove the edge agrees

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

A release is complete when the required public-edge checks agree with the artifact you chose, not merely when upload exits zero. This tutorial connects build, check, publish, and verify, while distinguishing local checks from deployment changes. Publishing changes the server; only the final probes are read-only network observations.

The commands assume Bash, GNU find/sort/sha256sum, rsync, Python 3, and the project’s pinned Hugo. Run build steps from the repository root. Before touching a live host, rehearse the directory-switch example in a disposable directory. Know the actual serve root, who owns deployment, the previous release target, and the rollback procedure. The /srv layout below is an example requiring an already configured deployment, not something this repository automatically installs.

The pointer switch changes the failure boundary. Before it, stop with the old release; after it, roll back explicitly and verify again. Disk checks and edge samples establish different facts.

1. Build one artifact from recorded inputs

Start from a clean source revision. Run the project build and record the installed generator version:

set -eu
git status --short
git rev-parse HEAD
hugo version
make build

An empty short status supports a clean-tree claim; the command itself does not enforce one. Inspect any changes before calling the build a release of that commit. make build writes data/buildinfo.toml with the short commit and current UTC build time, then generates public/. The rendered marker identifies the recorded inputs; it is not proof that a dirty checkout contained only that commit.

Pinning Hugo and the vendored theme reduces drift, but the build-time field means ordinary builds at different times need not be byte-identical. Build the chosen release once, validate it, and transfer that exact artifact rather than rebuild independently on the server.

2. Check the complete offline contract

make check checks generated visuals, offline-pack freshness, internal links, script-free output, source links, and downloadable checksums for the current artifact. For the full repository gate, use:

set -eu
make verify
make check-upstream

The full gate also runs regression tests, bilingual-post checks, and review-ledger freshness, then rebuilds and checks output. Therefore create the release manifest only after the last build. Build success and a current review ledger do not establish technical correctness of every article or prove the public server uses the intended headers. Page counts and timings vary; retain actual output rather than comparing to a copied example count.

3. Name the artifact bytes in a manifest

Before hashing, verify that public/ contains only directories and regular files, and stop all writers until staging is complete. The commands below do not create a snapshot or check for every special-file type. Keep the manifest outside public/ so it cannot hash itself. NUL-delimited filenames preserve spaces and other shell-sensitive characters:

set -euo pipefail
manifest="$(pwd)/release.sha256"
(
 cd public
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 sha256sum
) > "$manifest"
(cd public && sha256sum -c "$manifest")
sha256sum "$manifest"

GNU checksum lines contain the digest before the filename. A successful sha256sum -c verifies listed files, not that no extra files exist. A new empty release directory avoids stale destination files, but does not detect extra source files added after hashing. To establish complete regular-file inventory parity, recompute the staged manifest with the same path/sort/hash rules and compare the full lists before selection. Inspect symlinks separately: find -type f does not include them, and serving an unintended symlink can expose files outside the intended root. Keep the manifest and its own digest with the release record; a checksum proves consistency against that manifest, not authenticity of an untrusted manifest.

4. Stage and select a complete release

Assume Caddy already serves /srv/www/example-site/current, which is a symlink into releases/, with correct ownership and read permissions. The releases parent must already exist. Serialize deployers and choose a unique release ID. Run this block as a standalone Bash script on the deployment machine, from the directory containing the validated public/ and release.sha256. Check the artifact’s ownership and readable permissions against the deployment policy before running it. It establishes its own manifest path and fail-fast policy; a failed precondition, copy, or checksum must stop before pointer selection. It refuses symlinks inside the staged artifact and is a mutating deployment step.

set -euo pipefail
base=/srv/www/example-site
manifest="$(pwd)/release.sha256"
test -f "$manifest"
test -d public
release_id=20261015T120000Z
release="$base/releases/$release_id"
test -L "$base/current"
previous=$(readlink "$base/current")
mkdir "$release" # Fail if this release already exists.
rsync -a public/ "$release/"
(cd "$release" && sha256sum -c "$manifest")
links=$(find "$release" -type l -print -quit)
if [ -n "$links" ]; then
 echo "Refusing symlinks in the staged artifact" >&2
 exit 1
fi
# Ownership and readable permissions must match the deployment policy.
python3 - "$base" "$release_id" <<'PYTHON'
from pathlib import Path
import os, sys, uuid
base = Path(sys.argv[1])
release = base / "releases" / sys.argv[2]
current = base / "current"
if not current.is_symlink() or not release.is_dir():
 raise SystemExit("Expected current symlink and a complete release directory")
pending = base / (".current-" + uuid.uuid4().hex)
pending.symlink_to(os.path.relpath(release, base), target_is_directory=True)
os.replace(pending, current)
print("selected:", os.readlink(current))
PYTHON
printf 'Previous target: %s\n' "$previous"

The symlink replacement uses one same-filesystem rename because the pending link and current share a parent. An ordinary mv new existing-directory does not exchange non-empty directories. Do not convert an existing real-directory serve root with this snippet; plan that migration separately. Validate the actual server’s root resolution and filesystem behavior in staging.

The old target stays on disk, but that alone does not make an old asset URL reachable after switching. Retain fingerprinted asset bytes in the newly served namespace or a stable asset store. Multiple browser requests can span releases, and caches may keep old HTML. Atomic namespace replacement is not cross-request snapshot isolation or a power-loss durability guarantee.

5. Verify delivered bytes and policy

After switching, compare a sampled public body with the corresponding artifact file, using a fixed representation selection:

set -euo pipefail
url=https://www.xbcatm.com/
status=$(curl -sS --max-time 20 -H 'Accept-Encoding: identity' \
 -D served.headers -o served.html -w '%{http_code}' "$url")
test "$status" = 200
cmp public/index.html served.html
sh public/downloads/check-http-headers.sh "$url"

Run this block from the same artifact directory used for staging. The header helper is the trusted copy inside that artifact; a source checkout is not required for this step. cmp succeeding establishes exact parity for this homepage sample. An unexpected redirect, proxy-generated 200 error page, CDN transformation, or encoded response needs investigation. Inspect served.headers, including Content-Encoding, cache age, CSP, and content type. The header helper prints responses and final status; it does not enforce all your expectations.

Repeat for Chinese content, a nested article, CSS, an SVG, a download, redirects, and the error route. Document the URL-to-file mapping, including directory indexes. The shown listed-file check establishes consistency for those files, not a complete staged inventory or what all public cache nodes deliver. A complete edge claim requires broader retrieval and representation-aware checks; a few probes remain samples.

If a post-switch check fails, the new release is still selected until you act. Use a new temporary symlink targeting the recorded previous value, atomically replace current again, and repeat the probes. Do not merely move the new tree away, and do not delete evidence or the previous release while diagnosing.

6. Check TLS identity and the expiry window separately

From the repository root, the expiry helper is:

sh static/downloads/check-tls-expiry.sh www.xbcatm.com 30

It extracts a certificate, prints dates, and checks the remaining expiry interval. It is not a full TLS identity test: its current implementation does not make hostname/trust verification failure fatal. Follow the public-edge trust tutorial for an explicit verified handshake and SAN check. Do not infer trust-chain or revocation success from “valid for at least 30 days.”

A near-expiry certificate is a separate release concern. Preserve the actual notAfter, trust result, and client environment rather than copying a historical issuer or date into the release log.

7. Include the DNS cache window when DNS changes

A content-only release need not change DNS. If the host or edge changes, preserve service at the old destination while caches expire. Lowering TTL at the moment of the change does not shorten entries already cached with the old TTL. Resolver serve-stale behavior, negative caching, and client caches can complicate the window; TTL is not a universal deadline by which every client has moved. CAA changes affect issuance policy, not routing to the new content.

8. Keep a rehearsed restore path

The previous directory is useful for fast rollback, but it is not an independent backup. A disk failure, accidental cleanup, or compromised deployment account may affect every local release. Retain source, build inputs, configuration, and an appropriate separate artifact backup; rehearse restoring them in isolation. One successful rehearsal is evidence about that recovery path at that time, not a permanent guarantee for later changes.

9. Record the outcome precisely

Keep the source revision and clean-tree status, build metadata and tool versions, manifest digest, selected and previous targets, probe timestamps, HTTP/TLS observations, and any rollback. State whether verification covered samples, all mapped URLs, or multiple vantage points. If a gate failed, record the failure and recovery rather than “it worked.”

Before selection, a failure can leave the old release untouched. After selection, recovery is an explicit operation with its own verification. This distinction makes the release path auditable without pretending every failure automatically restores the old tree.

Sources

rsync manual, archive copying and source trailing-slash semantics, checked 2026-10-15.
RFC 8767: Serving Stale Data, DNS serve-stale behavior beyond TTL expiry, checked 2026-10-15.
GNU sha256sum manual, Debian package, checksum output and verification flags, checked 2026-10-15.
Python os.replace, atomic replacement and filesystem limits, checked 2026-10-15.
Caddy file_server, root and symlink handling, checked 2026-10-15.
curl manual, status capture, headers, and content decoding, checked 2026-10-15.
OpenSSL s_client, explicit certificate verification, checked 2026-10-15.
Reproducible Builds: definitions, artifact identity versus reproducibility, checked 2026-10-15.

A release checklist for a static site

Thu, 30 Jul 2026 00:00:00 +0000

A static site is simple to publish, but simplicity does not remove the need for a release check. The useful checks are small enough to run on every release and specific enough to fail for a real reason.

The checks belong to the generated artifact. Clean output does not establish reproducibility; placeholder searches are review aids, with parser-based link checks as the gate. Serve the exact artifact before publishing, compare public GET bodies afterward in both languages, and keep the commit, generator version, and download checksums.

Build a clean artifact

Use a pinned generator version and build into a disposable output directory:

set -eu
hugo version
hugo --cleanDestinationDir --gc --minify --destination public

--gc collects unused build-cache resources; it does not clean stale published pages. --cleanDestinationDir removes stale destination files, so use it only on the disposable artifact directory, never a directory containing source or unrelated data. Compare the printed version with the project’s pin; printing a version does not enforce it. Record the build inputs and verify the resulting artifact. A clean destination does not establish byte-for-byte reproducibility: timestamps and other nondeterministic inputs need separate control and comparison. Do not edit generated HTML by hand after the build.

Check the artifact, not only the source

Inspect the generated tree and verify that expected entry points exist. Run this assertion block as a standalone shell script; it must stop before printing the inventory if any required file is missing or empty:

set -eu
test -s public/index.html
test -s public/404.html
test -s public/robots.txt
test -s public/sitemap.xml
find public -type f -print | sort

Then search for accidental placeholders, local paths, and development-only hosts:

rg -l 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '*.html'

This is a review aid, not an automatic release gate: examples like this checklist deliberately match, including in translated pages. This HTML-only scan does not cover XML feeds or JSON search output. rg exits 1 when there are no matches and 2 on an error. Review each listed file, distinguish fenced examples from active links or attributes, and use a parser-based link check for the actual gate. A private path in a published link is a release mistake.

Exercise the public routes

An isolated production-like server pointed at this exact artifact gives the strongest pre-release routing check. Hugo’s development server rebuilds content; the following is a separate source preview, not evidence that the already checked public/ bytes were served. Run the first command in one terminal and the requests in another:

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://127.0.0.1:1313/ \
 --disableFastRender --disableLiveReload --renderToMemory
curl -I http://127.0.0.1:1313/
curl -I http://127.0.0.1:1313/notes/
curl -I http://127.0.0.1:1313/resources/
curl -I http://127.0.0.1:1313/missing-page/

HEAD checks do not compare bodies. Repeat with GET against the staged server, then after publishing compare public bodies with the artifact and check both languages. Confirm that the missing route returns a 404 status in the production server. A pretty error page with a 200 status still breaks monitoring and caches.

Record the result

Keep the source commit, generator version, and checksum of each downloadable resource in the release record. This makes it possible to compare a live file with the source that produced it without relying on memory.

The downloadable version of this checklist is in the Resources section.

Sources

Hugo command reference, generator flags for a clean production build, checked 2026-07-30.
curl manual, HTTP verification and header inspection options, checked 2026-07-30.
Static-site release checklist, downloadable companion resource.
Hugo server command reference, development rebuilds, memory rendering, and live-reload controls, checked 2026-10-15.

A release manifest should name every published byte

Thu, 16 Jul 2026 00:00:00 +0000

A static artifact is a directory, not one executable. Recording only the source commit or homepage checksum leaves gaps: a missing image, stale alias, or changed download can survive unnoticed. Enumerate every regular file in a frozen artifact before transport.

Freeze writers, reject symlinks and special files, and keep both manifests outside the artifact trees. A listed-file check detects missing or changed bytes; recomputing and comparing the complete lists also detects extras. Hashing the trusted source manifest supplies a compact identifier, with separate controls for authenticity and metadata.

Generate a stable list

Run this in Bash with GNU findutils and coreutils, from the directory containing public/. Keep the manifest outside the measured tree. The release must contain only directories and regular files: inspect and reject symlinks or special files first, since they are outside this manifest’s contract.

set -euo pipefail
manifest="$PWD/release.sha256"
(
 cd public
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$manifest"
test -s "$manifest"

Sort filenames before hashing. NUL-delimited paths preserve spaces, tabs, and embedded newlines between tools; GNU sha256sum escapes special names in its ordinary checkable output. Do not parse that output with awk '{print $2}': whitespace is legal in filenames. The separate assignment preserves a failed find exit status; testing only its output could mistake a failed scan for an empty result. Treat any failed scan or pipeline as an incomplete manifest and do not publish it. Stop writers while measuring; these commands do not create a filesystem snapshot.

Verify after transport

In one disposable Bash session on the destination, run the remaining fragments in order so the paths and set options stay in scope. Set the manifest and artifact paths to their actual locations:

set -euo pipefail
manifest=/path/to/release.sha256
artifact=/srv/www/site.new
(
 cd "$artifact"
 sha256sum -c "$manifest"
)

Checking listed files catches missing or changed bytes, but not extra files. Recompute the destination manifest with the same procedure and compare the complete records:

observed=$(mktemp "${manifest}.observed.XXXXXX")
trap 'rm -f "$observed"' EXIT
(
 cd "$artifact"
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$observed"
diff -u "$manifest" "$observed"

No diff and exit status zero means the regular-file paths and hashes agree. An extra stale file now fails too. The temporary output remains outside the artifact so the check never includes itself. Empty directories, permissions, ownership, and timestamps are not measured; validate those separately if deployment depends on them.

Add an aggregate digest for release records

Hash the manifest itself for a compact release identifier:

sha256sum "$manifest"

Its meaning depends on fixed rules: relative paths, sorting locale, algorithm, tool format, and included metadata. Keep the trusted manifest with the source commit and builder version.

Do not confuse integrity with authenticity

Matching SHA-256 digests are strong practical evidence of matching bytes, not proof of authorship. An attacker able to replace both artifact and manifest can make the check pass. Signing and trusted distribution are separate controls; verify only a manifest obtained through the intended trusted channel.

Sources

GNU Coreutils: sha2 utilities, checksum generation and verification; reviewed through the linked upstream manual source, checked 2026-10-15.
GNU Coreutils manual source, untagged checksum escaping, --check, and NUL-delimited sorting, checked 2026-10-15.
sha256sum(1), command behavior and output format, checked 2026-07-16.
GNU Bash: Simple Command Expansion, assignment-only commands retain command-substitution exit status, checked 2026-10-18.

A release is not complete until the public edge agrees

Thu, 09 Jul 2026 00:00:00 +0000

Static publishing removes application runtime complexity, but it does not remove the boundary between a generated directory and a public response. A release check should cover both.

Use the same artifact before and after selection. The download row refers to public/downloads/check-http-headers.sh in the article. Supported content codings are decoded before cmp; server transformations need a documented rule. Status and header checks are separate. Retain the previous directory for a deliberate rollback.

Start from a clean artifact

Build with the pinned generator into a clean destination. Record the source commit, generator version, output file list, and checksums of files that users download. A clean build catches stale files that a copy-over deployment can accidentally preserve.

set -eu
make verify
find public -type f -print | sort

The file list is evidence, not decoration. If a route disappears, the diff should explain whether the source was removed or the generator failed to emit it.

Exercise three response classes

Before publishing, test the staged artifact with the intended server configuration. After switching directories, repeat these checks at the public edge; probing the old live site cannot validate the new release. Request one HTML page, one static resource, and one missing path. Inspect status, content type, cache policy, and security headers:

set -eu
curl --compressed -fsS -D page.headers -o page.body https://www.example.test/
curl --compressed -fsS -D asset.headers -o asset.body \
 https://www.example.test/downloads/check-http-headers.sh
curl --compressed -sS -D missing.headers -o missing.body \
 https://www.example.test/does-not-exist

cmp public/index.html page.body
cmp public/downloads/check-http-headers.sh asset.body
cmp public/404.html missing.body

Run each fragment as a standalone shell script or in a disposable shell session. set -eu stops this sequential script after a failed build, transfer, or comparison, so a later successful command cannot hide an earlier failure. The missing-path request intentionally does not use -f: a 404 is expected and should still be captured. Check the final status in each header file: 200, 200, then 404; the byte comparisons do not automate that status check. No redirect is followed here. --compressed decodes supported content codings before comparison; a deliberate server-side HTML transformation needs its own documented comparison rule. cmp is silent on equality and returns nonzero on a difference. Repeat for /zh/ and its error page rather than assuming language parity.

Keep rollback simple

Do not delete the previous directory until the new one has passed the checks. A rollback should select a known-good directory, not reconstruct one from memory during an incident. The release checklist and HTTP header check are deliberately small enough to run from a clean shell.

Sources

RFC 9110 — HTTP Semantics, status and representation semantics, checked 2026-07-09.
curl manual, response inspection options, checked 2026-07-09.
Static-site release checklist, local companion resource.

Publish a static site by switching complete directories

Mon, 01 Jun 2026 00:00:00 +0000

Copying new files directly over a live static directory creates a period where visitors can receive HTML from one release and assets from another. A safer pattern stages one complete tree beside the live tree, verifies it, then changes directory names.

These two moves leave live absent between them; crashes can prolong the gap. Restore must be attempted and checked. Old asset URLs must remain reachable across separate browser requests.

Keep all release directories on one filesystem

Keep the live tree, staged tree, and rollback tree on the same filesystem. These fragments assume one Bash session, GNU Coreutils, and a single deployer with exclusive access to these names. Stop on a failed command or either side of the copy pipeline:

set -euo pipefail
df -P /srv/www

Create a uniquely named stage directory under that parent. Do not reuse an unresolved variable or broad wildcard as a deletion target.

stage=$(mktemp -d /srv/www/site.new.XXXXXX)

Populate and verify the stage

Copy the generated artifact into the empty directory, then check representative files. The final command displays a count; compare it with the verified artifact’s expected count or manifest rather than treating any number as a pass:

tar -C public -cf - . | tar -C "$stage" -xf -

test -s "$stage/index.html"
test -s "$stage/404.html"
find "$stage" -type f | wc -l

Run link and checksum checks against the staged path when the tooling supports a directory argument. Also verify that the serving user can traverse the directories and read the files: mktemp -d starts with restrictive permissions, and the extracted artifact must supply the intended modes. A stage that has not passed verification must never acquire the live name.

Switch names with an explicit rollback path

Resolve every path before the first move:

live=/srv/www/site
stamp=$(date -u +%Y%m%dT%H%M%SZ)
rollback=/srv/www/site.old-$stamp

test -d "$live" && test ! -L "$live" || exit 1
test -d "$stage" && test ! -L "$stage" || exit 1
test ! -e "$rollback" && test ! -L "$rollback" || exit 1
df -P "$live" "$stage"
live_device=$(stat -c %d -- "$live") || exit 1
stage_device=$(stat -c %d -- "$stage") || exit 1
test "$live_device" = "$stage_device" || exit 1

mv -T -- "$live" "$rollback" || exit 1
if mv -T -- "$stage" "$live"; then
 test -s "$live/index.html"
else
 mv -T -- "$rollback" "$live" || {
 printf 'Restore failed; inspect %s and %s before retrying.\n' "$rollback" "$live" >&2
 exit 1
 }
 exit 1
fi

This is a two-step switch, not one atomic replacement: the live path is absent between moves, and a crash can leave it absent until recovery. GNU mv -T prevents an existing directory from silently becoming a container for the moved tree; it does not serialize competing deployers. Do not proceed if the filesystem check differs. Platform-specific atomic exchange or symlink replacement can remove the missing-name interval, but must be tested with the actual server.

Verify the public edge

After the switch, request the homepage, one deep route, one fingerprinted asset, and a missing path. Compare public bytes with the staged artifact. Keep the rollback directory until that check and the observation window complete.

Even an atomic name switch does not make a browser’s HTML and asset requests one transaction. Keep older fingerprinted assets reachable for cached or in-flight HTML; merely retaining an unserved rollback directory does not do that. A filesystem rename also makes no promise of crash durability without the platform-specific persistence steps.

Sources

POSIX rename(), name replacement semantics, checked 2026-06-01.
Linux rename(2), filesystem and replacement behavior, checked 2026-10-15.
GNU tar manual, archive creation and extraction, checked 2026-06-01.
GNU Coreutils: Target directory, -T and directory nesting hazards, checked 2026-10-15.
GNU Coreutils: stat, filesystem device-number checks, checked 2026-10-15.

Release · XB Field Notes

Hugo publication flags decide what enters the artifact

Separate publication metadata from build options

A preview artifact can still be published

When it breaks

Check it quickly

Sources

Git tags pin a release to a commit

Two kinds of tags

Why sign a release

Move with care

When it breaks

Check it quickly

Further reading

Sources

Rolling updates replace pods in small waves

The surge and the gap

Health gates replacement

Choose a deliberate pace

When it breaks

Check it quickly

Further reading

Sources

Blue-green deployment keeps two environments ready

Define what the switch controls

Keep data compatible across the overlap

When it breaks

Check it quickly

Sources

Ship a static site and prove the edge agrees

1. Build one artifact from recorded inputs

2. Check the complete offline contract

3. Name the artifact bytes in a manifest

4. Stage and select a complete release

5. Verify delivered bytes and policy

6. Check TLS identity and the expiry window separately

7. Include the DNS cache window when DNS changes

8. Keep a rehearsed restore path

9. Record the outcome precisely

Sources

A release checklist for a static site

Build a clean artifact

Check the artifact, not only the source

Exercise the public routes

Record the result

Sources

A release manifest should name every published byte

Generate a stable list

Verify after transport

Add an aggregate digest for release records

Do not confuse integrity with authenticity

Sources

A release is not complete until the public edge agrees

Start from a clean artifact

Exercise three response classes

Keep rollback simple

Sources

Publish a static site by switching complete directories

Keep all release directories on one filesystem

Populate and verify the stage

Switch names with an explicit rollback path

Verify the public edge

Sources