HomeHow this site runs Selected work

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.

In words. I push a commit to master. A GitHub webhook tells the machine. Helios fetches the repository with a read-only deploy key and builds the image, and the build runs the release gate. If a check fails, the deploy stops there and the running revision keeps serving. If the gate passes, Helios starts the new revision beside the old one, checks it, and switches traffic to it. It then checks 14 named pages after the deploy and every minute after that.

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 agentsllms-full.txt, from scripts/llms-full.mjs.
  • The sitemap and the contact cardsitemap.xml and 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

  1. npm run iris:check

    Hashes the imported Iris files against their pin.

  2. npm run check:html

    Validates every source page as HTML.

  3. npm run check:js

    Parses every browser script and every build script.

  4. node scripts/check-games.mjs

    Checks the archived games, which stay out of production.

  5. npm test

    Runs 48 test files with Node’s test runner.

  6. npm run build

    Builds every page with Vite and writes the data into the HTML.

  7. npm run check:build

    Validates 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.

Read about Helios

  1. A webhook, not a pipelineGitHub tells the machine when master moves, and Helios fetches the repository with a read-only deploy key.
  2. The gate is part of the buildThe image build runs the whole release gate, so a push that fails it never becomes a revision.
  3. 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 rollback can bring it back.
  4. 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
  • /contains Kyle Begeman
  • /assets/data/career.jsoncontains "ledger"
  • /docs/career-data.mdcontains Career data: how the site is fed
  • /projects/ledger/contains Ledger
  • /projects/helios/contains Helios
  • /projects/ophelia/contains /projects/helios/
  • /sitemap.xmlcontains projects/ledger/
  • /linkscontains Save contact
  • /connect/contains Hire me
  • /boop/contains Save contact
  • /kyle-begeman.vcfcontains BEGIN:VCARD
  • /links/card/contains Share page
  • /r/contains Private rooms have closed
  • /llms-full.txtcontains # 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; includeSubDomains
X-Content-Type-Options
Stops browsers guessing a file’s type.
nosniff
X-Frame-Options
Keeps other sites from framing these pages.
DENY
Referrer-Policy
Limits what another site learns about where a visitor came from.
strict-origin-when-cross-origin
Permissions-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 host
utm_medium=shortlink
utm_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.

Need the product built and kept running?