A deployment is a proof chain, not a file copy

A release starts before the network. Run the tests, type checks, and static build against one source revision, then treat the resulting build directory as a candidate rather than a scratch folder. If a second build is created after the archive is made, there are now two releases and the operator has to guess which one was tested.

The exact commands vary by stack. The invariant is that the artifact comes from the same gate that produced the evidence. For a JavaScript static site, a minimal local contract looks like this:

1set -eu2npm test3npm run check4npm run build5tar -czf release.tar.gz -C build .6sha256sum release.tar.gz > release.tar.gz.sha256

A commit identifies intent. A digest identifies the exact artifact. A deployment needs both. Record the source revision, artifact digest, target environment, and previous-release reference in a small manifest or receipt. A timestamp helps humans find the event, but it is not an identity: two different artifacts can share a minute, and the same artifact can be promoted more than once.

The digest is deliberately boring. It lets the receiving side answer a narrow question without trusting the transport narrative: do these bytes match the candidate that was tested? That question does not require a heavyweight platform, only a stable archive and a verification command.

Copying directly into the live document root collapses transfer, extraction, validation, and promotion into one irreversible-looking action. A temporary stage restores the boundaries. Transfer the archive, verify its digest, extract it to a new directory, and inspect the files there before the active root changes.

The stage check should be specific. Confirm the entry document exists, a representative deep route resolves to the expected generated file, the feed or sitemap is present when advertised, and assets are readable by the serving process. A directory listing is not a browser test, but it catches a surprising number of bad copies.

A static generator can produce the right files while the server still serves the wrong URL behavior. Clean routes, trailing slashes, fallback documents, feeds, redirects, and content types are part of the application contract. Test them against the staged tree and the serving configuration, not only against a local development server.

For Nginx, try_files makes the lookup order visible: check the requested file or directory, then redirect internally to the chosen fallback. That is powerful precisely because it is concrete. If a note route works only because a development server invents a fallback, the release is not ready.

The header-only commands below are reachability smoke checks. Pair them with representative body markers and a browser pass before calling the release verified.

1# syntax/referenced-file gate2nginx -t3# header-only reachability smoke checks4curl --fail --silent --show-error --head https://example.com/5curl --fail --silent --show-error --head https://example.com/notes/example6curl --fail --silent --show-error --head https://example.com/feed.rss

Reloading a server only says that the process accepted an instruction. It does not say that the new root is complete, that the edge points at the intended origin, or that client-side hydration can load its assets. Verification must cross layers: inspect the serving process, request the public HTML, follow one deep route, fetch machine-readable surfaces, and load a representative page in a real browser.

The browser pass is not ceremony. It catches stale asset manifests, failed module requests, console exceptions, duplicate landmarks, horizontal overflow, and interaction regressions that curl cannot see. Keep the browser fixture small and repeatable: home, one heavy note, one mobile viewport, and one reduced-motion pass are more useful than an unbounded manual tour.

• HTTP: status, content type, and representative body markers from a body fetch.
• Server: configuration test, container/process health, and reload result.
• Browser: no failed resources or console errors, no document overflow, and usable article controls.
• Record: release digest, verification time, and the exact rollback archive.

Rollback is not a dramatic recovery plan reserved for outages. It is the normal answer to a failed smoke check. Archive the previous root before promotion, keep the archive tied to the release receipt, and make the reversal use the same serving-layer validation as the forward path. A rollback that has never been rehearsed is a hope with a filename.

The safest small-site rollback is intentionally unglamorous: stop the promotion, restore the last known tree, validate the configuration, reload, and re-run the public probes. Do not “fix forward” while the release identity is still unclear; that produces a second unknown artifact and makes the incident harder to explain.

1set -eu2rsync -a --delete previous-release/ live-root/3nginx -t4nginx -s reload5# reachability smoke check; repeat body/browser checks6curl --fail --silent --show-error --head https://example.com/

The pattern is small enough to run without a deployment platform and strict enough to prevent the most expensive category error: confusing a successful copy with a successful release. Build once. Identify the bytes. Stage them. Validate the router and the reader-facing surface. Preserve the previous state. Promote only after the evidence is present. Verify from outside the process. Keep the reversal close.

That chain scales upward. Larger systems add signed attestations, immutable registries, progressive traffic shifts, and automated policy gates; they do not remove the underlying questions. What changed? What exactly moved? What is serving it? How do we know? What was live before it? How do we return there without improvising?