Static-Web · XB Field Notes

Readable evidence before dashboards

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

Monitoring dashboards are convenient, but convenience is not the same as evidence. This essay argues that for a small static service, the most auditable form of “is the site healthy?” is a set of plain-text facts an operator can read, re-run, and paste into a report — not an aggregated panel.

The distinction matters because the two answer different questions. A dashboard is a lens over many samples, tuned to alert you to trends. A probe is a single, reproducible observation of the public edge. When the job is to prove a release or diagnose a specific request, the probe is the higher-fidelity artifact.

A response supports a scoped claim. Repeated observations support trends when the underlying records and their provenance remain inspectable.

The dashboard’s aggregation is the risk

A dashboard turns thousands of raw observations into a series of aggregated panels: average latency, error rate, uptime percentage. Aggregation is where the audit trail thins. An “uptime 99.98%” figure does not tell you which request failed, which header was wrong, or whether today’s release is the one being served. It is a summary that erases the evidence that produced it unless you keep the raw log elsewhere.

For a confidence property like “the edge serves the tree I staged”, a dashboard is the wrong tool. A response-body comparison can answer that question for one URL, representation, network vantage point, and instant. A homepage header fetch cannot establish the identity of a whole tree or every CDN node.

A probe you can read

The repository ships a small read-only helper, static/downloads/check-http-headers.sh, also published at /downloads/check-http-headers.sh. It prints response headers and the final status/URL. The following is an illustrative excerpt, not a new production measurement:

HTTP/2 200
content-type: text/html; charset=utf-8
content-security-policy: default-src 'self'; …; script-src 'none'; …

A real capture can directly show the response status, declared media type, and delivered CSP. The abbreviated example above cannot establish a complete no-script policy: inspect the full enforcing header, including any script-src-elem or script-src-attr directives that take precedence for their categories. A Report-Only policy does not block execution. A panel that says “edge OK” should expose the same underlying capture and acceptance criteria. Both still depend on the probe implementation, TLS verification, routing, and retention of the original output. Reading certificate notAfter adds an expiry observation; it does not establish hostname matching or trust-chain validity.

Replace signal loss with a checkable statement

The mechanism the site favors instead of a dashboard is a contract enforced during build and a set of repeatable collection steps for the release window. Roughly:

Offline checks validate the artifact (every internal link, every SVG, the no-script boundary, the checksums).
Separate public-edge checks record status/headers, response bytes, and TLS identity/expiry. The header helper does not print certificate dates or automatically reject every unexpected HTTP status.
A byte manifest describes the staged tree; retrieving selected URLs and comparing their bodies establishes sampled delivery parity. A complete claim requires checking all published mappings and representation transformations, not merely hashing the server disk.

Each of these is a sentence an operator can paste into an issue or a changelog and a future auditor can re-run. None of them requires a panel to be understood.

Keep enough context to repeat the observation

Record UTC time, requested and final URL, method, selected encoding, resolved remote IP, client version, exit status, HTTP status, relevant headers, and body digest. Preserve failures as well as successes. Redact credentials, cookies, and personal data before sharing logs. A proxy error page returning 200 can pass a status-only check; comparing a known body or release marker catches a different failure mode.

A useful release report distinguishes “this response matched at this time” from “the service met its availability objective over a month.” Retain the raw observations behind aggregate metrics, and make a dashboard link back to them where possible. Neither display format creates trustworthy measurements by itself.

When you genuinely need a dashboard

None of this says observability is pointless. If you operate many instances, aggregate capacity, or long trends, a dashboard is the right view to see the forest. The claim is narrower: when the question is “is this one release healthy at the public edge”, a reproducible terminal read is a good starting point. Repeated probes, several vantage points, error budgets, and alerting add evidence about intermittent or regional failures that a single successful request cannot supply. A well-designed dashboard can expose those observations without hiding their provenance.

The decision heuristic is simple. If a claim can be checked with one command, preserve that command’s output together with its scope and acceptance criteria. Use dashboards where aggregation helps, while retaining access to the underlying evidence. That keeps the site’s own operational story as auditable as the site’s content.

Sources

Curl documentation, reading response headers from a single invocation, checked 2026-10-15.
Twelve-Factor: Logs, treating logs as event streams an operator can read, checked 2026-10-15.
OpenTelemetry: Observability primer, the complementary roles of logs, metrics, and traces, checked 2026-10-15.
W3C: Content Security Policy Level 3, enforcing versus Report-Only delivery and script directive precedence (working draft), checked 2026-10-18.

Freshness and validation in the two-clock cache model

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

Caching has two separate decisions: may a stored response be reused without contacting the server, and how can the client check whether that response still represents the resource? Calling them “two clocks” is a mnemonic. Freshness really is an age calculation; validation is a comparison, not another timer. A response can be fresh by policy while already differing from a newly deployed origin, without the cache violating HTTP.

Simplified age example: matching variant, no overriding request directive. no-cache still requires validation; must-revalidate forbids unvalidated stale reuse. Validator matching does not prove byte identity.

Freshness: how long to reuse without asking

Cache-Control: max-age=60 gives a response a freshness lifetime of 60 seconds. A cache compares that lifetime with the response’s current age, accounting for Date, Age, transit time, and time stored. At exactly 60 seconds it is stale, not fresh for one more second. Shared caches prefer s-maxage when present; absent explicit freshness, some responses can receive heuristic freshness.

A fresh response is usually reusable, but matching the cache key and Vary fields and obeying request/response directives still matters. no-cache requires successful validation before reuse even when the response could otherwise be fresh. no-store prohibits storage; it is not a synonym for revalidate. public permits shared-cache storage in cases otherwise restricted; it does not specify a duration.

For mutable HTML, a short explicit lifetime plus validation is often useful. It intentionally permits updates to take up to that lifetime to become visible through a compliant cache. A whole-tree deployment does not invalidate existing browser or CDN entries. Content-addressed assets can instead use a long lifetime when the URL changes with the bytes.

Validation: ask whether the stored representation still matches

An ETag is an opaque validator, not a checksum the client should decode. Last-Modified is a timestamp validator. Neither header specifies an explicit freshness lifetime, and a server need not supply both. When heuristic freshness is permitted, however, a cache can use Last-Modified to estimate a lifetime. For example, these illustrative headers express a lifetime and a validator separately:

Cache-Control: max-age=60, must-revalidate
ETag: "release-a"

After expiry, If-None-Match: "release-a" lets a GET receive 304 Not Modified if the selected representation still matches, or a new 200 with a body if it changed. The cache updates applicable metadata from the 304 and reuses its stored body. A 304 is not useful without a corresponding stored representation. If-None-Match uses weak comparison, so successful validation does not necessarily prove byte-for-byte identity; If-Range and combining partial responses have stronger requirements.

The server can compute an ETag from bytes or other reliably changing metadata. A strong tag must distinguish representations whose data differs, including content codings where applicable. Sending the same strong ETag for different gzip and identity bytes is not fixed by adding a short lifetime. Vary: Accept-Encoding also tells a cache which request header affected selection.

A small exercise that separates the decisions

This Python model deliberately excludes heuristic freshness, network delay, and variant selection. age stands for the already calculated current age; the conditional request uses a server validator that has not changed. The model compares two fixed tag strings; it does not implement HTTP entity-tag parsing, tag lists, or the full weak-comparison rules.

lifetime = 60
stored_etag = '"release-a"'
server_etag = '"release-a"'
for age in (59, 60, 61):
 fresh = age < lifetime
 action = "reuse without validation" if fresh else (
 "validate: 304, reuse body" if stored_etag == server_etag
 else "validate: 200, replace body"
 )
 print(age, action)

The first line reuses without validation; the other two validate and reuse after a 304. Set server_etag to "release-b": the stale cases become 200, while the 59-second case still reuses the stored response. That is the permitted visibility delay the freshness policy buys in exchange for lower latency and origin load.

The contract worth asserting

Test matching and changed validators, freshness at the boundary, and the selected encoding. Also decide what should happen during an origin outage. HTTP can permit stale reuse under defined conditions or extensions; must-revalidate prohibits reusing the response once stale without successful validation, even when disconnected. This increases correctness pressure at the cost of availability. A validator alone makes no such promise.

A useful release record therefore states the cache policy, selected representation, observed conditional status, and tolerated update delay. Requiring two validator headers and one 304 cannot prove that every cache has current bytes, prevent all bandwidth waste, or replace testing the actual intermediary configuration.

Sources

RFC 9111: HTTP Caching, sections 4.1–4.3 and 5.2 on variants, age, validation, and directives, checked 2026-10-15.
RFC 9110: HTTP Semantics, sections 8.8, 13.1.2, and 13.1.5 on validators and comparison, checked 2026-10-15.

The zero-JavaScript static site is a defensible choice

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

A static site does not need JavaScript to be defensible; the absence of a <script> tag can itself be the point. This essay argues the engineering case for shipping a site whose script lanes are closed by policy, then explains how to verify the policy at the public edge. The header below is the repository’s intended configuration, not a fresh observation of production.

The argument has three parts: the threat surface you delete, the contract that makes deletion observable, and the cases where deleting the layer is the wrong call.

Assumes the article’s complete enforcing CSP with no more-specific script allowance. Report-Only does not block. The three checks shown are required evidence, not completed tests.

The threat surface you delete by not having a script lane

A page that executes no own or third-party script removes the client-side script dependencies that would otherwise need patching and review. An effective no-script CSP blocks injected script execution in conforming browsers, but HTML injection can still change text, links, and page structure. Trackers can also use images, navigation, or server logs without JavaScript. This site separately avoids third-party browser dependencies; that is a broader requirement than removing script tags. Browser-bundle dependency drift disappears when there is no bundle, while build-tool and server dependencies remain. Each of these is a bounded, nameable surface — the small-systems property of choosing boundaries you can articulate.

None of this claims the site is “secure”. It claims the attack surface is narrower and, crucially, easier to reason about because it is enumerated by construction rather than by audit.

The header that makes the boundary enforceable

A taste is not a policy. The difference here is that the server delivers a policy that the browser enforces. The example Caddy configuration in this repository specifies:

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:

The script-src 'none' directive is the enforceable part. With this complete policy and no more specific script allowance, a conforming browser refuses page scripts, inline handlers, and JavaScript URLs. A Content-Security-Policy-Report-Only header would only report violations, not block them. Later additions of script-src-elem or script-src-attr need review because they can override the fallback for their respective script categories.

The build verifier checks generated artifacts for executable scripts, handlers, and URLs. It cannot prove that a reverse proxy serves the intended CSP. Fetch representative HTML, error pages, and redirect destinations separately; inspect the actual enforcing header and test browser behavior. Source inspection, response inspection, and browser execution are three distinct checks.

What the static structure buys after the removal

With no scripting, the content model reverts to something closer to published documents. Caching operates on HTTP representations, not on a page’s later DOM mutations. Static output makes those representations easy to inspect and version; an ETag and freshness policy still depend on server configuration. Reading the served HTML in a terminal, using view-source, or indexing the tree is straightforward because the artifact is ordinary files on disk. The trade the site accepts is deliberate: no script-managed state, no client-side rendering, and no feedback that needs a JavaScript view model. Native links, keyboard navigation, CSS behavior, and elements such as details can still provide interaction. For a documentation and operations site that is the correct exchange, and it is worth writing down.

When the zero-JS claim is the wrong call

The boundary is a feature, not a badge of purity. A site that genuinely needs client-side interactivity — a realtime dashboard, a document editor, a payment flow — should not contort itself into serving static HTML and then bolting on a workaround. The wrong application of this decision is to shave a product to fit the constraint. The right application is to recognize that content that is read, searched, and archived profits from being a document, and to reserve scripting for where a document is insufficient.

For this property, the served header is useful evidence for the response sampled. It does not prove universal browser support or that every route has the same policy. Keep the underlying content safe to render, protect publishing access, and maintain the generator and server. The boundary is defensible precisely when its limits are explicit.

Sources

W3C: Content Security Policy Level 3, policy delivery, script directives, and directive fallback (working draft), checked 2026-10-15.
MDN: Content Security Policy (script-src), directives that disable script execution, checked 2026-10-15.
PortSwigger: What is cross-site scripting (XSS)?, script injection and its consequences, checked 2026-10-15.
OWASP: Content Security Policy, CSP as a defense-in-depth control, 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.

Security headers should describe the actual page

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

Security headers are not a substitute for secure code, but they make the browser enforce useful boundaries. The policy should describe the page that is actually served, not a generic template copied from another project.

Treat headers as a deployment contract: match actual resources, distinguish enforced and report-only policy, and verify exact host scope and browser behavior.

Start from the resource graph

If a site serves HTML, a local stylesheet, a favicon, and no executable JavaScript, a narrow policy can be understandable:

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:

The script-src 'none' choice is only correct while the site does not require executable scripts. Adding search, comments, or an analytics tag changes the resource graph and should trigger a deliberate policy review.

Add transport and framing protections

For an HTTPS-only site, the following headers are common starting points:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()

Only enable HSTS with includeSubDomains when every subdomain is prepared to serve HTTPS. A header is a contract with future deployments, not merely a score in a scanner.

Check behavior, not just presence

Request a normal page, a missing page, and a static asset. Error responses should carry the same important security headers as successful responses. Also confirm that compression and caching do not change the content type or expose an internal path.

The Caddy example in this site is a starting point, not a universal policy. Adapt the host names, certificate handling, and application routes to your own deployment.

Deliver the CSP as a response header. frame-ancestors is ignored in a meta policy and does not inherit default-src; form-action also needs its own directive. style-src 'self' does not allow inline styles by itself, so test the generated theme, including dark mode. Keep data: in img-src only when the page actually needs data images.

Content-Security-Policy-Report-Only can reveal violations during a rollout, but does not enforce the policy; a reporting endpoint needs separate configuration. Verify enforcement in a real browser as well as checking headers. HSTS is learned from valid HTTPS responses; with includeSubDomains it also applies to descendants of the host that sets it: a policy on www.example.test does not cover the parent example.test or sibling api.example.test. Gradually increase the lifetime after checking that exact scope.

Sources

MDN: Content Security Policy guide, CSP directive names and syntax, checked 2026-07-23.
MDN: Strict-Transport-Security, HSTS directives and deployment cautions, checked 2026-07-23.
Caddy header directive, response header manipulation directives, checked 2026-07-23.
W3C Content Security Policy Level 3, response-header delivery, directive fallbacks, framing, and report-only policies; current working draft, checked 2026-10-15.
RFC 6797 — HTTP Strict Transport Security, valid HTTPS delivery and host/descendant matching in sections 8.1–8.3, checked 2026-10-15.

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.

Content-Type should describe the bytes you actually send

Thu, 11 Jun 2026 00:00:00 +0000

A static server can return the correct bytes with the wrong Content-Type. The page may still look acceptable in one browser, while a download, stylesheet, feed reader, or security policy treats the same response differently. The public response header is the contract; the filename is only an input to server configuration.

A suffix cannot prove what arrived. Read the public response status, bytes, and media type together; an HTML error page at a CSS path is not a mapping test. Nosniff makes script and style type mismatches visible.

Inspect representative formats

Check one HTML document, stylesheet, SVG, feed, and downloadable script. Include headers but discard the body:

for path in / /assets/site.css /favicon.svg /index.xml /downloads/check-http-headers.sh; do
 curl -sS -D - -o /dev/null "https://www.example.test$path" \
 | awk -v path="$path" '
 BEGIN { print "== " path }
 /^HTTP\// || tolower($1) == "content-type:" || tolower($1) == "x-content-type-options:" { print }
 '
done

Replace the example asset paths with files that actually exist in the release; an HTML 404 response at an invented CSS path is not a MIME-mapping test. Expected media types depend on the resource, but they should be specific and stable. HTML should normally include a character set. CSS and SVG should not be served as generic binary data. A shell helper offered for download should not be advertised as HTML.

This loop displays headers; it does not assert success, inspect the discarded bytes, or exercise browser blocking. Confirm the resource against the release artifact and inspect an actual browser load as a stylesheet or script. Opening the same URL as a document tests a different request destination.

Keep nosniff consistent

X-Content-Type-Options: nosniff asks supporting browsers to respect the declared type for script and style destinations instead of guessing. For that Fetch check, a script-like destination needs a JavaScript MIME type, and a style destination needs text/css; a missing or unusable type also fails. This turns a mismatch into an observable failure rather than browser-dependent interpretation.

The header does not repair a wrong type or make arbitrary content safe. Check the inventory while deploying it, and fix any rejected script/style response rather than removing the protection:

X-Content-Type-Options: nosniff

Check the server mapping

Static servers usually derive types from extensions. If a new extension is served as application/octet-stream, decide whether that is intentional before adding a global override. A narrow mapping is easier to review than a rule that changes every response.

Repeat the checks at the public hostname. A CDN or reverse proxy can replace a correct origin header, and a friendly error page can return HTML for a path whose suffix looks like CSS or JavaScript.

Sources

RFC 9110 — HTTP Semantics, representation metadata and Content-Type, checked 2026-10-15.
MDN: Content-Type, media types and charset examples, checked 2026-10-15.
MDN: X-Content-Type-Options, nosniff behavior, checked 2026-10-15.
WHATWG Fetch Standard, script-like and style destination blocking, checked 2026-10-15.

Why a small site can stay static

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

A static site serves documents prepared before their requests arrive. The important question is whether visitors need different server-generated representations, rather than how many pages the site contains. Hundreds of articles can share one publishing model: edit sources, build HTML and assets, validate the output, then expose those files through a web server or CDN.

Put document generation at the right boundary

When an article means the same thing for every reader, assembling it on every request often adds little value. Templates, navigation, translations, and indexes can be resolved during a build. The serving path then needs the published files, not the authoring database or generator. Requests can still be logged, encrypted, cached, and access-controlled; static delivery does not remove these responsibilities.

Static HTML can include JavaScript and interactive controls. A client-side search index may suit a modest public collection, whereas private search or personalized results need a service that enforces access. Forms, comments, payments, and authenticated mutations likewise require appropriate processing. Identify those boundaries separately: making the article static does not make a browser authoritative for permissions or durable state.

Build-time generation moves work rather than eliminating it. Large collections can have expensive rebuilds, dependencies can fail, and content freshness is limited by the publishing pipeline. A new source edit is not automatically visible. For time-sensitive material, measure edit-to-publication delay, keep build failures visible, and verify the released document instead of assuming a successful editor save reached readers.

When it breaks

A common failure is serving the repository root. Source data, build scripts, or private drafts may then become downloadable even though no navigation links mention them. Use a dedicated output directory containing only intended artifacts. Excluding a document from an index is different from excluding its file from publication. Inspect the actual release inventory, including copied assets and generated search data.

Another failure is updating files individually while requests arrive. An HTML page can reference an asset not yet uploaded, or an old page can lose a dependency deleted during cleanup. Prepare complete releases, preserve necessary old assets, and use the hosting platform’s supported switch mechanism. Restoring an old source commit alone does not restore dependencies, artifacts, cache state, or external services.

Static output also carries injection risks. Untrusted text needs context-appropriate escaping; inserting it directly into HTML can turn an article value into active markup. Escaping text does not validate arbitrary URLs, sanitize intentionally allowed HTML, or protect JavaScript contexts. Review the actual template positions and source trust instead of treating static generation as automatic security.

Editing a source does not publish it. Static illustration of the source and its limits. Reported fixture outcomes were not rerun for this graphic.

Check it quickly

Save the following as static-build.py and run python3 static-build.py with Python 3. It creates a temporary source outside a public directory, builds one HTML file, and serves only that directory over loopback. The script exercises publication with actual HTTP requests and removes its temporary files after closing the server.

from functools import partial
from hashlib import sha256
from html import escape
from http.client import HTTPConnection
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Thread
import json
import os


class Handler(SimpleHTTPRequestHandler):
 def log_message(self, *args):
 pass


with TemporaryDirectory() as directory:
 root = Path(directory)
 public = root / 'public'
 public.mkdir()
 source = root / 'source.json'
 source.write_text(json.dumps({'title': 'Version one', 'text': 'Published content'}))

 def build():
 content = json.loads(source.read_text())
 document = f'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>{escape(content["title"])}</title></head><body><h1>{escape(content["title"])}</h1><p>{escape(content["text"])}</p></body></html>'
 pending = root / 'next.html'
 pending.write_text(document)
 os.replace(pending, public / 'index.html')
 return document.encode()

 first = build()
 server = ThreadingHTTPServer(('127.0.0.1', 0), partial(Handler, directory=str(public)))
 thread = Thread(target=server.serve_forever)
 thread.start()
 try:
 def fetch(path='/'):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 return response.status, response.read()
 finally:
 connection.close()

 source.unlink()
 assert fetch() == (200, first)
 source.write_text(json.dumps({'title': 'Version two', 'text': '<b>literal text</b>'}))
 assert fetch() == (200, first)
 second = build()
 assert fetch() == (200, second) and second != first
 assert b'&lt;b&gt;literal text&lt;/b&gt;' in second
 assert fetch('/source.json')[0] == 404
 print(json.dumps({'serves_without_source': True, 'edit_requires_rebuild': True,
 'published_sha256': [sha256(first).hexdigest(), sha256(second).hexdigest()],
 'source_not_published': True, 'text_escaped': True}))
 finally:
 server.shutdown()
 thread.join()
 server.server_close()

First, the program deletes the editable source and still receives the previously published bytes. It recreates a changed source but confirms that requests continue returning version one until build runs again. The second build changes the document digest and returns version two. Its literal <b>literal text</b> is escaped in the HTML, and a request for /source.json returns 404. Expect all four behavior flags true and two different published hashes.

These checks passed with Python 3.14.4. The replacement uses os.replace on the same filesystem for one complete file. It does not demonstrate atomic publication of a multi-resource site, crash durability, automatic rollback, or a particular hosting provider’s deployment mechanism. The experiment isolates the source-to-artifact boundary. For a real release, inspect all generated files, test representative links and missing paths, and verify caching alongside artifact availability. Choose static delivery when this boundary matches the product, then operate the build and serving layers with their own observable checks.

Sources

GitHub Docs: About GitHub Pages, static hosting from published HTML, CSS and JavaScript files, checked 2026-09-13.
MDN: Introduction to the server side, static and dynamic response generation, checked 2026-09-13.

A static server should have one obvious root

Thu, 04 Jun 2026 00:00:00 +0000

The most useful property of a static deployment is that an operator can answer “which directory served this response?” without reading application code. Caddy’s root and file_server directives provide that boundary directly.

Make the serving directory explicit. Audit symlinks and read/traverse permissions, then verify the actual response at the edge.

Make the root explicit

A minimal site block can be kept close to the artifact layout:

www.example.test {
 root * /srv/example-site
 encode zstd gzip

 header {
 -Server
 X-Content-Type-Options nosniff
 X-Frame-Options DENY
 Referrer-Policy strict-origin-when-cross-origin
 }

 file_server
}

The hostname and path are placeholders; www.example.test is not a publicly issuable production name. Use an owned, resolvable hostname for production and plan local TLS trust separately for a test environment. The release command should publish a complete directory, verify it, and only then make that directory the configured root. Keep the prior known-good directory until the new one has passed smoke tests.

Check the edge, not only the file tree

Request an HTML page, a downloadable text file, and a missing path. Compare content types and status codes with the local artifact. A 404 page that returns 200 is a deployment bug even if the page looks polished.

When Caddy manages HTTPS, certificate provisioning and HTTP-to-HTTPS redirects are part of the edge behavior. Test the redirect from the bare HTTP listener and the certificate name from the public hostname. Do not infer success from a healthy process alone.

A root is a publication boundary, not a sandbox

Keep source control metadata, backups, credentials, and private configuration outside the published tree. Caddy follows symlinks inside the root, so a link can expose files outside it. Check both the artifact contents and the serving user’s read/traverse permissions. Also, merely placing 404.html in the tree does not configure a custom error handler; verify the missing-route status and error-page behavior you intend.

Sources

Caddy file_server directive, file serving, root, and index defaults, checked 2026-10-15.
Caddy Automatic HTTPS, automatic TLS and issuance behavior, checked 2026-10-15.
Static-site release checklist, local companion resource.
Caddy header directive, response header operations, checked 2026-10-15.
RFC 7034 — X-Frame-Options, the DENY framing policy, checked 2026-10-15.
MDN: X-Frame-Options, framing options, checked 2026-10-15.
RFC 6761 — Special-Use Domain Names, reserved .test names, checked 2026-10-15.

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.

Static-Web · XB Field Notes

Readable evidence before dashboards

The dashboard’s aggregation is the risk

A probe you can read

Replace signal loss with a checkable statement

Keep enough context to repeat the observation

When you genuinely need a dashboard

Sources

Freshness and validation in the two-clock cache model

Freshness: how long to reuse without asking

Validation: ask whether the stored representation still matches

A small exercise that separates the decisions

The contract worth asserting

Sources

The zero-JavaScript static site is a defensible choice

The threat surface you delete by not having a script lane

The header that makes the boundary enforceable

What the static structure buys after the removal

When the zero-JS claim is the wrong call

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

Security headers should describe the actual page

Start from the resource graph

Add transport and framing protections

Check behavior, not just presence

Sources

A release is not complete until the public edge agrees

Start from a clean artifact

Exercise three response classes

Keep rollback simple

Sources

Content-Type should describe the bytes you actually send

Inspect representative formats

Keep nosniff consistent

Check the server mapping

Sources

Why a small site can stay static

Put document generation at the right boundary

When it breaks

Check it quickly

Further reading

Sources

A static server should have one obvious root

Make the root explicit

Check the edge, not only the file tree

A root is a publication boundary, not a sandbox

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