Site case study
How this site runs.
This site is part of the work it shows. Every page is built from one file of facts, has to pass one command, and is deployed by a tool I wrote. This page follows a change from a commit to the live site.
Readouts
Read from the repository when this page was built.
- Site version
- 0.1.24
- package.json
- Helios, pinned
- 0.7.13
- helios.pin.json
- Deploy checks
- 14
- helios.yaml
- Public pages
- 15
- sitemap.xml
- Test files in the gate
- 48
- scripts/
*.test.mjs - Production size
- 10.0 of 25 MiB
10.0 of 25 MiB - dist/, measured after the build
The path
From a push to a checked revision.
A push to master is the whole release. Helios deploys on that push without waiting for CI, so the release gate runs inside the image build itself.
git pushA commit lands on master.npm run check.A failed check stops here. The running revision keeps serving.01 / Data
One file of facts.
Every project, role and skill on this site lives in one file, career.json. When a page is built, a script reads that file and writes the finished HTML into it, so the home page, the résumé and the work history cannot disagree with each other.
It also means the pages are complete without JavaScript. The browser reads the same file again only for the extras, such as the project filter and the site navigator.
Built from career.json
- Home, résumé and work historyFilled at build time by
scripts/career-prerender.mjs. - Open-source project pagesOne page per repository, from
scripts/project-routes.mjs. - The plain-text profile for AI agents
llms-full.txt, fromscripts/llms-full.mjs. - The sitemap and the contact card
sitemap.xmland a vCard, written by the production build.
02 / Gate
One command decides.
npm run check is the release gate. It is the same command on my laptop, in CI and inside the image build. It runs these steps in order and stops at the first one that fails.
The Dockerfile runs it in the build stage, and the image that ships is made from that stage’s output. A failed check is a deploy that never starts.
Before a push I run npm run check:local, which first validates helios.yaml with the pinned Helios release. The binary is downloaded once and hashed against the pin on every run.
npm run check, from package.json
npm run iris:checkHashes the imported Iris files against their pin.
npm run check:htmlValidates every source page as HTML.
npm run check:jsParses every browser script and every build script.
node scripts/check-games.mjsChecks the archived games, which stay out of production.
npm testRuns 48 test files with Node’s test runner.
npm run buildBuilds every page with Vite and writes the data into the HTML.
npm run check:buildValidates the built HTML, then checks fingerprints, local links, JSON, contact details, the security policy, the sitemap and the size budget.
03 / Deploy
Helios deploys it.
Helios is my own deploy tool, and it is open source. It is one static Go binary that runs a machine: builds, certificates, secrets, backups, health checks and alerts. An app describes itself in a helios.yaml at the root of its repository.
This site’s manifest names the web workload built from the Dockerfile, the hostnames it answers on, and the pages to check. This repository validates it against Helios 0.7.13.
- A webhook, not a pipelineGitHub tells the machine when master moves, and Helios fetches the repository with a read-only deploy key.
- The gate is part of the buildThe image build runs the whole release gate, so a push that fails it never becomes a revision.
- The old revision stays until the new one is checkedThe new revision starts beside the old one and is checked before traffic switches. The old one is retained, and
helios rollbackcan bring it back. - The checks keep runningThe
checks:block names 14 addresses, each with text the answer must contain or a status it must return. Helios runs them after every deploy and every minute after that.
The 14 checks in helios.yaml+
/containsKyle Begeman/containsassets/ data/ career.json "ledger"/containsdocs/ career-data.md Career data: how the site is fed/containsprojects/ ledger/ Ledger/containsprojects/ helios/ Helios/containsprojects/ ophelia/ /projects/ helios/ /containssitemap.xml projects/ledger/ /containslinks Save contact/containsconnect/ Hire me/containsboop/ Save contact/containskyle-begeman.vcf BEGIN:VCARD/containslinks/ card/ Share page/containsr/ Private rooms have closed/containsllms-full.txt # Kyle Begeman
These are the pages generated at build time and the old addresses that must keep forwarding, so they are the ones worth failing a deploy over.
04 / Headers
Caddy sends the promises.
The image is small: Caddy serving the built files as a user without privileges. The headers the site promises live in the Caddyfile, beside the files, so they travel with every deploy.
The Content Security Policy allows inline code only by hash. scripts/csp.mjs reads the built pages, hashes every inline script and style, and writes the policy. The build check fails when the Caddyfile falls behind, and when any page gains an inline event handler or a style attribute.
The policy is enforced: the header is Content-Security-Policy, and a browser refuses anything it does not allow. npm run csp:pass loads every page in headless Chrome and fails on any violation.
On every response, from deploy/Caddyfile
Strict-Transport-Security- Tells browsers to use HTTPS only.
max-age=31536000; includeSubDomainsX-Content-Type-Options- Stops browsers guessing a file’s type.
nosniffX-Frame-Options- Keeps other sites from framing these pages.
DENYReferrer-Policy- Limits what another site learns about where a visitor came from.
strict-origin-when-cross-originPermissions-Policy- Turns off browser features the site never uses.
camera=(), microphone=(), geolocation=(), payment=(), usb=()Content-Security-Policy- Lists what a page may load and run. Inline code is allowed only by hash.
default-src 'self', 3 inline script hashes, 5 inline style hashes
05 / Guards
What the build refuses to ship.
Three rules are checked against the built files, not against my memory of them.
- No stray contact details
The site publishes one email address, the contact link, and no phone number. The check scans every text file it ships and fails on a phone-shaped number, a telephone link or field, or any other email address.
scripts/privacy.mjs - A size budget
The whole production output has to fit in 25 MiB. No single file may be larger than 300 KiB, or 4 MiB for a video. The build copies a reviewed list of files, not the whole public folder, and the check fails when any limit is passed.
scripts/production-assets.mjs - Names that match contents
Stylesheets, scripts, images and fonts are named after a hash of their bytes, so Caddy can mark them immutable. The check recomputes every hash and fails on a mismatch.
scripts/check-build.mjs
06 / Iris
One design system, shared.
Iris is the design system I keep for my sites and apps: one set of colour, type, spacing and motion tokens, with components built on them. Boop’s Studio is built on the same package.
This site imports Iris 0.7.26 as a pinned release. The gate starts by hashing each imported file against the pin, so a copy edited by hand fails before anything else runs.
Tokens on this page, in the theme you are reading
--iris-bg--iris-paper--iris-band--iris-line--iris-muted--iris-ink--iris-accent--iris-ember
Every colour in this page’s stylesheet is one of these tokens. Switch the theme and they all change together.
07 / Boop and analytics
Links in, page views out.
Boop is the service behind my link page and my short links. The link page lives at boop.at, and the old /links addresses on this site forward there. A short link that points here arrives with three tags, and they name the link that sent the visit.
Analytics is first-party and small. One script sends a page view to my Sites utility, and the page view carries the whole original query, which is how a visit is credited to its short link. Once it is sent and the page has loaded, the tags leave the address bar, so a copied link does not pass them on.
The script sends only from the production hostname, so a dev server or a preview reports nothing. It sets no cookie and stores nothing in the browser. Cloudflare sits in front of the site and adds its own Web Analytics beacon, which the policy allows by host.
What analytics.js sends
- A short link adds
utm_source, the link’s hostutm_medium=shortlinkutm_campaign, the link’s name- A page view carries
- The path, the referrer, the query and the window width.
- A named event for
- A click on a link that leaves the site, an email link, or a control marked
data-track. - Sent from
- The production hostname only.