Tutorials · XB Field Notes

Ship a static site and prove the edge agrees

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

A release is complete when the public edge agrees with the files you chose — not when the final upload command exits zero. This tutorial turns that sentence into a repeatable procedure using the checks the release-and-recovery notes describe. Everything before the last phase is safe to run locally; the only remote step is the read-only probe at the end.

The workflow has four phases that each produce evidence the next phase consumes: build, check, publish, and verify.

Before you begin, make three facts explicit so a failure is cheap: how to run the build (make build), which single directory the live site serves, and how to rename that directory back to the previous tree. Writing those three answers down first turns the whole procedure from a hope into a script with a visible rollback. The rest of the tutorial assumes you can answer them.

1. Build a single, reproducible artifact

Start from a clean control tree, not from whatever is currently on the server. The small-systems note argues for boundaries you can name; a static build needs only a handful. Run the project target:

$ make build
…
 Pages │ 130 │ 128
 Static files │ 42 │ 42
 Total in 171 ms

The build writes a fingerprint into data/buildinfo.toml — the source commit and build time — which the home page renders. Keeping that fingerprint inside the artifact lets a later reader prove which source tree produced the bytes, so an audit does not have to guess.

2. Verify against the offline artifact contract

Before touching the live host, run the checks that need no network. These confirm the artifact is internally consistent on its own:

$ make check
validated 257 HTML documents; internal targets and script-free contract are intact

The verifier validates every generated SVG, walks every internal link and fragment, enforces the no-JavaScript contract, and verifies the downloadable checksums. It fails on a broken artifact rather than on a slow network — the property reliable-defaults calls making the main path boring.

3. Name every byte in a manifest

A release claim must be able to say exactly which bytes changed and then prove they are the ones served. Hash the artifact into a sorted manifest:

$ cd public && find . -type f | sort | sed 's#^./##' | xargs sha256sum > /tmp/release.sha256
$ grep robots.txt /tmp/release.sha256
robots.txt f6ad425cbc898cef00d4b62bef6b17dc627de9ee0c910b31dcc1ee4d054f3d24

The release-manifest notes name every published byte so the “edge agrees” claim can be checked byte-for-byte. Keep this manifest for the whole release window; you will compare it against the served tree after the swap.

4. Publish by switching complete directories

Do not overwrite a live tree file-by-file. Stage a full tree beside the existing one, then switch the single directory name Caddy serves — the atomic-switch note calls this complete-directory publication:

$ 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 instant and nothing is ever half-written. The old tree is still there, so rollback is a single rename in the other direction (reliable-defaults).

5. Confirm the public edge agrees with what you staged

Before trusting the swap, prove the served status and headers match the artifact. The read-only-release-smoke-tests and read-public-edge notes both make this the final gate — run the helper and read its output:

$ ./downloads/check-http-headers.sh https://www.xbcatm.com/
HTTP/2 200
content-type: text/html; charset=utf-8
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:

A 200 with the correct CSP and content type is the first agreement. The second agreement is bytes: hash the served tree and compare to the manifest from step 3. When they match, the edge is the tree you staged. If the served HTML differs, stop — you are looking at the wrong tree.

6. Confirm the certificate window before you finish

The release is not done until the certificate is healthy too. check-tls-expiry reads the validity window without breaking the TLS session:

$ ./downloads/check-tls-expiry.sh www.xbcatm.com 30
subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

certificate remains valid for at least 30 day(s)

A near-expiry certificate turns a “successful” release into an imminent incident. The certificate-expiry note and the release checklist both make the TLS window part of the release condition rather than a later surprise. Read notAfter as a concrete date, not a dashboard color.

7. Mind the DNS cache window

If your release changes DNS records (a host change, a CAA update, or a new edge), remember the change propagates on a schedule you do not own. The dns-change-window note shows why a rollback must include the cache-aware window, not just the record. A release that looks complete locally can still be mid-propagation at a remote resolver for as long as the old TTL.

8. Back up a restore path, not just the bytes

Publishing is the other side of recovery. Before a release, verify there is a restore rehearsal — the backup-rehearsal note stresses that a backup is only useful after you have restored from it once. This release tutorial assumes the period restore step already works, because the recovery half of the series is what makes publishing reversible instead of risky.

9. Record the outcome a late operator can audit

When the swap is confirmed and the windows are checked, leave a factual record a future operator can trust: the commit, the manifest hash, and the two probe outputs. A postmortem entry is more useful when it names facts — which bytes, which status, which dates — than when it asserts “it worked”. Put the same facts in the changelog so the site’s own evolution stays auditable.

The path maps to the series

Phase	Evidence	Notes
Build	buildinfo fingerprint	small-systems, atomic-switch
Check	offline verify passes	reliable-defaults, release-checklist
Manifest	SHA-256 of every file	release-manifest, checksums
Publish	complete-directory swap	atomic-switch, caddy-static-files
Verify	HEAD parity + manifest hash	read-only-smoke-tests, public-edge
Cert	validity window as date	certificate-expiry
Record	commit + probe output	postmortem, changelog

Each stage consumes the previous stage’s evidence. If any stage fails, you stop and the old tree remains the served one — the property that makes the whole procedure safe to practice.

Sources

GNU Coreutils: sha2 utilities, per-file checksums and manifests, checked 2026-08-11.
POSIX rename(), complete-directory publication, checked 2026-08-11.
Caddy file_server, root selection and swap, checked 2026-08-11.
OpenSSL s_client, certificate dates, checked 2026-08-11.

Read a live edge the way a client does

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

The HTTP-foundations notes each take one contract and show single pieces of evidence. This tutorial walks the whole path a single client request touches, in order, using only read-only commands. By the end you will have reproduced, on any live static edge, the checks those notes describe — without changing its state.

We use www.xbcatm.com throughout. Replace it with the host you are inspecting. Every command below is read-only: it reads headers, requests metadata, or asks for a specific range; none of them writes to the origin.

1. Start with what a method may ask

Before you read a response body, pin down what the server will allow you to ask. A static origin has no transactions, so most mutating methods are rejected explicitly. Ask the edge what it allows:

$ curl -s -o /dev/null -w 'OPTIONS -> HTTP %{http_code}\n' -X OPTIONS https://www.xbcatm.com/
OPTIONS -> HTTP 405

405 Method Not Allowed is the honest answer. The http-method-semantics note explains why this is the contract a static origin should keep: every method is either supported with documented semantics or rejected with a status that says so. The dangerous failure mode is a proxy or imported handler that converts a rejected method into a silent 200. If your edge ever answers 200 to POST, the promise is no longer visible.

2. Read the representation line

The first line tells you the negotiated exchange; the headers then tell you what kind of bytes are coming. Capture them exactly as a client sees them, discarding the body:

$ curl -s -D - -o /dev/null https://www.xbcatm.com/
HTTP/2 200
accept-ranges: bytes
content-length: 15890
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
content-type: text/html; charset=utf-8
etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff

Three headers deserve a pause. content-type: text/html; charset=utf-8 names the media type, and content-type-and-nosniff shows why it must describe the actual bytes you send. etag: "dkx84jwth7nkc9e" hands you a strong validator. x-content-type-options: nosniff bids a browser not to guess the type. Each is evidence, not decoration, and together they say: this edge tells you exactly its policy before you trust the body.

3. Confirm HEAD equals GET but carries no body

HEAD must be safe and return the same metadata as GET, without a body. Compare the HEAD Content-Length (the bytes GET would return) with what you actually READ:

$ curl -sI https://www.xbcatm.com/ | grep -i content-length
content-length: 15890
$ curl -s https://www.xbcatm.com/ | wc -c
15890

They match: 15890 on both. That is the head-request-parity contract. If a proxy strips or rewrites the HEAD Content-Length, a pair of checks like this catches it. This is exactly why check-http-headers.sh reads status and headers together with curl and why the release smoke tests compare HEAD before and after a swap.

4. Ask for precise bytes with a range

Because the origin knows its representation, it can serve part of it. A range request asks for a byte span and gets only that span:

$ curl -s -o /dev/null -H 'Range: bytes=0-99' -w 'HTTP %{http_code} bytes=%{size_download}\n' https://www.xbcatm.com/
HTTP 206 bytes=100

206 with 100 bytes for a 100-byte range is the honest result. The http-range-requests note explains how the server selects which bytes and why a strong validator is required. If a server answers 200 with the full body to any range instead, that is a different, more expensive contract — and it tells you the origin does not track the byte identity you asked for.

5. Let the cache revalidate with a validator

Now combine method, representation, and byte selection through caching. A stored copy is current only if the validator still matches. Replay your ETag conditionally:

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'If-None-Match: "dkx84jwth7nkc9e"' https://www.xbcatm.com/
HTTP 304

304 Not Modified is a small header-only reply that tells you the copy you asked about is still the answer. That is the conditional-requests contract: validation decides whether a stored copy is fresh, while http-cache-headers describes two clocks — freshness from the cache headers, and correctness from the validator. A 304 is never an error; it is the cheap way to say “you already have the right bytes”. When the ETag changes, the next revalidation returns a fresh 200.

6. Negotiate a smaller representation when you can

The same content can travel in fewer bytes when the client says it can decompress. Offer gzip and watch the body shrink while the meaning stays identical:

$ curl -s -o /dev/null -w 'no-enc: %{size_download} bytes\n' https://www.xbcatm.com/
$ curl -s -o /dev/null -H 'Accept-Encoding: gzip' -w 'gzip: %{size_download} bytes\n' https://www.xbcatm.com/
no-enc: 15890 bytes
gzip: 4368 bytes

The plain GET returned 15890 bytes; the gzip negotiation returned 4368 for the same content. That is the http-compression-negotiation note’s core idea: changing the selected representation changes the bytes on the wire, and the metadata (content-length, encoding) changes with it. A client that requests compression and a cache that stores the encoded form must agree on which representation they selected, otherwise the cache serves a mismatch.

7. Follow the story when a URL changes

When identity changes, the response should say where the story continues rather than guess the body:

$ curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' -I http://www.xbcatm.com/ | head -1
308 -> https://www.xbcatm.com/

308 Permanent Redirect keeps the method and preserves the story, which is the concern of redirects-and-status-codes. Whether it is a 301/308 for a permanent move, or a 404 handled by the site, the status line is the first sentence of the story and should be read before the body.

8. Let the crawler read the map last

The edge is also read by machines that do not request HTML at all. Discovery answers two different questions, as robots-and-sitemaps explains. Confirm discovery points at the real sitemap:

$ curl -s https://www.xbcatm.com/robots.txt
User-agent: *
Disallow:
Sitemap: https://www.xbcatm.com/sitemap.xml

A host that answers its own hosts across robots, sitemap, and the HTTP headers is one whose operator has read the public edge before publishing it.

The whole path in one glance

Check	What it proves	Note
`OPTIONS` -> 405	origin rejects unsupported methods	http-method-semantics
`content-type` + `nosniff`	header names the real bytes	content-type-and-nosniff
HEAD == GET Content-Length	safe, head parity	head-parity
Range 0-99 -> 206/100	exact byte selection	http-range-requests
`ETag` -> 304	validator decides freshness	conditional-requests
308 follows method	redirects preserve the story	redirects-and-status-codes
robots -> sitemap	discovery answers differ	robots-and-sitemaps

Each row was a note; now it is a command you can run against any edge. Read the linked note when you need the details, and keep this table as your re-check before you trust an endpoint.

Sources

RFC 9110 — HTTP Semantics, methods, validators, and status codes, checked 2026-08-07.
RFC 9111 — HTTP Caching, freshness and revalidation, checked 2026-08-07.
RFC 7538 — 308 Permanent Redirect, method-preserving redirect, checked 2026-08-07.
curl manual, read-only inspection flags, checked 2026-08-07.

Audit the trust of a public edge

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

The web-security series treats security settings as contracts with scope and failure modes. This tutorial runs those contracts end to end, read-only, against a live host, and tells you what each answer means. It does not change the server; it inspects what the server will tell anyone. Use www.xbcatm.com below and substitute your own host throughout.

1. Start with the headers the edge advertises

The first contract is what a browser is told to allow. Fetch the headers with check-http-headers.sh (or any read-only fetch) and read the actual policy:

$ curl -s -D - -o /dev/null https://www.xbcatm.com/
HTTP/2 200
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY

Each header is a claim about a specific failure mode. content-security-policy with script-src 'none' is the strongest for a static site, and security-headers explains why the policy should match the actual page. strict-transport-security with includeSubDomains is the transport promise, and hsts-rollout warns it must be rolled out in measured steps because it is sticky. nosniff stops MIME-type guessing. A header you intend but did not verify is a bug, not a feature.

Step 1 is static, but it is the contract a browser sees first. For a static site, script-src 'none' is both safe and honest: there is nothing to execute, so nothing runs. The important habit is to compare what you believe the policy is with what the edge actually sends. A proxy that strips or adds a header silently changes the contract; the read-only fetch catches that drift. If you use a tool like check-http-headers.sh, it reads the status and headers together, which keeps the policy and the reachability claim in the same record.

2. Confirm the identity is real, not a guess

The TLS identity starts with the leaf certificate. Read its exact subject, issuer, and validity dates:

$ echo | openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com 2>/dev/null \
 | openssl x509 -noout -subject -issuer -dates
subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

The subject is the exact hostname, not a wildcard from an adjacent certificate, and notAfter is a concrete date. certificate-expiry treats that date as the release gate rather than a dashboard color. An operator should be able to quote notAfter from memory of the last audit, not discover it at renewal time.

3. Read the chain, not just the leaf

A leaf only has value inside a chain the client can walk to a trusted root. Ask the edge what chain it actually presents:

$ echo | openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com -showcerts 2>/dev/null | grep 'BEGIN CERT' | wc -l
4

With its leaf plus intermediates, that number is expected to be 4. The certificate-chain note explains why: the leaf must be signed by an intermediate you actually authorized, and the edge must send that intermediate so deep-validation clients succeed. Count of exactly one is a red flag on a public CA. A second reason to check the chain is that the identity you read in step 2 only proves the leaf; it does not prove the client can reach a root it trusts. The chain is what closes that gap. If the edge ever starts sending a different intermediate — say, a test CA one day — the count and the issuer of certificate 1 change before any element on the page does. Reading the chain is the cheapest way to notice that trust moved before it matters.

4. Trade a validator to prove freshness is intact

The conditional-requests note applies here too: a live edge should answer a 304 to a revalidation so caches and clients do not re-download. This is also evidence that caching is working as the headers promise:

$ curl -s -o /dev/null -w 'HTTP %{http_code}\n' -H 'If-None-Match: "dkx84jwth7nkc9e"' https://www.xbcatm.com/
HTTP 304

Because this site sticks to a script-free policy, the CSP never changes between releases; only the etag moves when bytes change.

5. Verify which CA is allowed to issue

TLS identity goes hand in hand with DNS policy. Confirm the CAA record authorizes the issuer you actually use, so only that CA can legally sign for the domain:

$ dig +short CAA www.xbcatm.com

dns-caa-records explains CAA as supplier of trust: it authorizes the issuer, making the certificate-chain audit meaningful. Without a CAA record, any CA can issue; with one, the intermediate from step 4 should trace back to an authorized issuer.

6. Check who holds the host key

The chain protects TLS, but another trust boundary is SSH access. A host key is the deployment record for the server you SSH into. ssh-host-key treats it as part of the record you pin before you trust a connection:

$ ssh-keygen -lf ~/.ssh/known_hosts | grep www.xbcatm.com

Confirm the fingerprint matches what you recorded when the host was added. A changed host key after a rebuild is either a legitimate reinstall or a reason to stop — this is exactly why host-key policy exists as a web-security boundary, not just a convenience.

Even a no-script static site can set cookies; if it does, their scope is a security claim. cookie-scope says a cookie’s host, path, transport, and same-site boundaries should be narrower than the application’s reach. Audit that no cookie is set for a broader scope than needed, and prefer Secure; HttpOnly; SameSite for anything sensitive.

The audit as a checklist

Signal	Read it as	Notes
CSP `script-src 'none'`	no-script policy is live	security-headers
HSTS `includeSubDomains`	transport promise is sticky	hsts-rollout
certificate subject+dates	identity is a concrete date	certificate-expiry
chain shows `4` certs	intermediates are sent	certificate-chain
`304` on revalidation	cache validator works	conditional
CAA authorized	only CA can issue	dns-caa
host key footprint matches	SSH trust is a record	ssh-host-key

Each signal was a note; together they are a single checklist. You add all these in under a minute with two read-only commands, leaving the server untouched.

Typical-procedure notes

This audit belongs in a scheduled check, not only at release. If you already have a set of checks, add the two openssl lines and the header fetch to them. Keep the outputs in a file named by date so a later comparison can show drift. That is how a static site stays evidence-first even when nothing is changing.

Sources

RFC 9110 — HTTP Semantics, validators and conditional requests, checked 2026-08-06.
RFC 6797 — HSTS, transport policy, checked 2026-08-06.
RFC 5280 — X.509 PKI, certificate chains, checked 2026-08-06.
OpenSSL s_client, chain and identity inspection, checked 2026-08-06.
dig(1), DNS record lookup, checked 2026-08-06.

Tutorials · XB Field Notes

Ship a static site and prove the edge agrees

1. Build a single, reproducible artifact

2. Verify against the offline artifact contract

3. Name every byte in a manifest

4. Publish by switching complete directories

5. Confirm the public edge agrees with what you staged

6. Confirm the certificate window before you finish

7. Mind the DNS cache window

8. Back up a restore path, not just the bytes

9. Record the outcome a late operator can audit

The path maps to the series

Sources

Read a live edge the way a client does

1. Start with what a method may ask

2. Read the representation line

3. Confirm HEAD equals GET but carries no body

4. Ask for precise bytes with a range

5. Let the cache revalidate with a validator

6. Negotiate a smaller representation when you can

7. Follow the story when a URL changes

8. Let the crawler read the map last

The whole path in one glance

Sources

Audit the trust of a public edge

1. Start with the headers the edge advertises

2. Confirm the identity is real, not a guess

3. Read the chain, not just the leaf

4. Trade a validator to prove freshness is intact

5. Verify which CA is allowed to issue

6. Check who holds the host key

7. Keep cookie scope narrower than the app

The audit as a checklist

Typical-procedure notes

Sources