Haunted Pavement

Caddy and Astro on one small VPS

Sat, 17 Oct 2026 00:00:00 GMT

This site is a folder of static files on a small ARM server. The same server runs the coding agents that help build it, a PostgreSQL that every app shares, and a Node app. Caddy sits in front of all of it. This post covers how that fits together: the Caddy block, a deploy that can’t take the live site down with a bad build, and a build that refuses to pass with a warning in its output.

One server, several apps

The rule for the box is that each app gets three things: a domain, a live copy in /srv/apps/<app>, and a line in a server map that says what runs where. A static site like this one is served straight from files. A Node app runs as a systemd user unit and gets its own port, and Caddy proxies its domain to it.

There’s no Docker and no connection pooler. PostgreSQL already runs natively on the server, one instance with a database per app, and plain systemd services are fewer moving parts on a box with one owner. When a new app needs a database, it gets createdb, not a container.

The live copy is a separate checkout from the ones where work happens. Agents and I edit in our own checkouts and worktrees, push a branch, and merge to main. Only the deploy script touches /srv/apps/. That separation is what lets several pieces of work go on at once without anyone breaking the live site halfway through an edit.

The Caddy block

At launch, all of hauntedpavement.com was this:

hauntedpavement.com {
	root * /srv/apps/hauntedpavement/.live
	file_server
}

www.hauntedpavement.com {
	redir https://hauntedpavement.com{uri} permanent
}

Caddy gets and renews the HTTPS certificates by itself, so there’s nothing else to configure for TLS. The www block sends everything to the bare domain, keeping the path.

One detail of file_server shaped the Astro config. A request for /posts finds a directory, and Caddy redirects it to /posts/. Astro builds every page as <path>/index.html, so the site uses the trailing-slash form everywhere, and every link it prints is already the URL Caddy serves without a redirect:

export default defineConfig({
  site: 'https://hauntedpavement.com',
  trailingSlash: 'always',
  build: { format: 'directory', inlineStylesheets: 'always' },
  // …
});

trailingSlash: 'always' also makes the dev server reject the other form, so a link without the slash shows up while writing, not in production.

A deploy that can’t break the live site

Publishing is one command, deploy hauntedpavement. Each app has a small settings file that names its kind (static or node), its domain, and its build output folder. For a static app, the script does this:

git fetch -q origin "$BRANCH"
git reset -q --hard "origin/$BRANCH"

build || die "build failed; the live site is unchanged"
mkdir -p .live
rsync -a --delete "$OUT/" .live/

Caddy never serves dist/. It serves .live/, and .live/ only changes after pnpm install --frozen-lockfile and pnpm build have both passed. The script also checks that the output has a home page, and stops if it doesn’t. Astro empties dist/ at the start of every build, so serving it directly would mean a failed build leaves an empty site behind. With the copy step in between, a failed build leaves the live site exactly as it was, and the script says so.

The copy itself isn’t atomic: for the moment rsync runs, the folder holds a mix of the old and new files. For a personal site that’s a fair trade. If it ever matters, the next step is to build into a fresh folder per release and swap a symlink to it.

A Node app gets the same idea in a different shape. A failed build resets the checkout to the commit that was live, rebuilds it and restarts the service, so the app keeps running the last version that worked.

A build that fails on any warning

deploy runs pnpm build, which means whatever pnpm build checks guards every deploy too. On this site it checks more than Astro does.

First, a short script reads every code file under src/ and fails, naming the file and line, if anything outside one module reads the content collections. That module, src/lib/content.ts, is the only place that applies the rule “drafts aren’t published”. A page that called getCollection() itself would skip that rule, and a draft could leak through one route, such as a tag page.

Then the build runs through a wrapper that watches its output line by line and fails if any line looks like a warning:

const WARNING_PATTERNS = [
  /\[WARN\]/, /\[Shiki\]/, /^\(!\)/, /Warning:/,
];

The patterns cover Astro’s own warnings, Shiki’s (an unknown language in a code fence), and Node’s (DeprecationWarning:, ExperimentalWarning: and the rest). Astro is happy to build a site with warnings, and that’s how a missing code language or a deprecated option can go unnoticed for months. Here the first such line fails the build, and so blocks the deploy, until its cause is fixed.

The wrapper reads the output with readline, so a pattern split across two chunks of output still matches. It sets NO_COLOR so colour codes can’t split a pattern either. It also drops FORCE_COLOR, because the test runner sets it, and with both set Node prints a warning of its own, which the gate would then catch.

The end-to-end tests build a second copy of the site from fixture content, into a separate folder, and the production build refuses to start if the variable that points it at fixtures is set. Test content can’t reach a deploy by accident.

Added after launch

The first block was the minimum. It didn’t compress responses, and a missing page got Caddy’s empty 404 instead of the site’s own. A few lines fixed both, and this is the block that runs now:

hauntedpavement.com {
	root * /srv/apps/hauntedpavement/.live
	encode zstd gzip
	header /_astro/* Cache-Control "max-age=31536000, immutable"
	file_server
	handle_errors 404 {
		rewrite * /404.html
		file_server
	}
}

Files under /_astro/ have a content hash in their name, so a changed file gets a new URL and the old one can be cached for a year. Pages keep their URLs, so they don’t get that header.

Lighthouse on an arm64 VPS with Playwright's Chromium

Sat, 17 Oct 2026 00:00:00 GMT

This site has to score at least 0.95 in every Lighthouse category (Lighthouse’s API scores from 0 to 1), on the home page and on a test post of a fixture build, checked on every test run rather than once by hand. The tests run on a small ARM server with Ubuntu 24.04 and no desktop browser, and Playwright’s own arm64 Chromium is already installed for the end-to-end tests. So Lighthouse runs inside a Playwright test, against that Chromium.

Why not the Lighthouse CLI’s own Chrome

The Lighthouse CLI starts its own browser through chrome-launcher. On this server it finds none:

The CHROME_PATH environment variable must be set to a
Chrome/Chromium executable no older than Chrome stable.

Pointing CHROME_PATH at Playwright’s Chromium gets further, then stops at “waiting for dynamic debugging port”. Chromium’s error log says why:

FATAL: No usable sandbox! If you are running on Ubuntu 23.10+
or another Linux distro that has disabled unprivileged user
namespaces with AppArmor, see …

Ubuntu 23.10 and later restrict unprivileged user namespaces through AppArmor, and Chromium’s sandbox needs them. Adding --no-sandbox to --chrome-flags, next to --headless=new since there’s no display, makes the CLI work:

CHROME_PATH=~/.cache/ms-playwright/chromium-1208/chrome-linux/chrome \
  lighthouse https://example.com --chrome-flags="--headless=new --no-sandbox"

Playwright already launches Chromium without the sandbox; its chromiumSandbox option defaults to false. Running Lighthouse from a test therefore needs no extra flag, uses the same browser build as the rest of the suite, and puts its reports in the same HTML report. Turning the sandbox off is fine for auditing your own pages; for untrusted ones, see Chromium’s AppArmor notes.

Port 0 and DevToolsActivePort

Lighthouse drives the browser over the Chrome DevTools Protocol, so it needs a debugging port. A fixed port such as 9222 can collide with anything else on the server. Port 0 asks Chromium to pick a free one and write it to a file named DevToolsActivePort in its profile directory.

That’s why the test uses a persistent context: its profile directory is one the test chose, so it knows where the file will appear. chromium.launch() uses a temporary profile whose path the test never sees.

profileDir = await mkdtemp(join(tmpdir(), 'hp-lighthouse-'));
context = await chromium.launchPersistentContext(profileDir, {
  channel: 'chromium',
  args: ['--remote-debugging-port=0'],
});
port = await readDevToolsPort(profileDir);

channel: 'chromium' selects the full Chromium build in its new headless mode, rather than the separate headless shell that Playwright uses by default.

The file can appear a moment after the launch returns, so readDevToolsPort() polls it every 100 ms for up to 10 seconds, and accepts only a first line that is all digits. Each run gets a fresh mkdtemp directory, so a stale file from an earlier run can never be read. The directory is deleted afterwards.

Lighthouse’s Node API then connects to that port:

const result = await lighthouse(url, {
  port,
  output: 'html',
  logLevel: 'error',
  onlyCategories: [...CATEGORIES],
});

No configuration is passed, so it audits with the default mobile settings: an emulated phone and simulated throttling.

The scores as test annotations

Each page is one test. It writes the HTML report to test-results/lighthouse/ and attaches it to the test, so the full report opens from the Playwright report. Each category’s score becomes an annotation, which shows the numbers next to the test without opening anything. Then each category gets a soft assertion:

for (const id of CATEGORIES) {
  expect.soft(categories[id].score, `${id} on ${path}`)
    .toBeGreaterThanOrEqual(MIN_SCORE);
}

expect.soft keeps checking after a failure, so one run lists every category below 0.95, not only the first. A runtimeError in the result fails the test outright, because a run that couldn’t load the page has no meaningful scores.

What it caught

The first run failed. A post scored 0.93 on performance, with a Cumulative Layout Shift of 0.158. The display face used for titles arrived after the first paint. A size-adjusted fallback font can’t match a condensed face’s width, so when it swapped in, the title rewrapped and pushed the article down. Preloading that face next to the body face brought the shift to 0 and performance to 1.0. Every page already downloaded the file, so the fix changed only when it arrives, not how much is sent.

Both pages now score 1.0 in all four categories, and the suite fails if either drops below 0.95.

Nearest neighbours in PostGIS

Sat, 17 Oct 2026 00:00:00 GMT

“Find the five places closest to this point” sounds simple, and the obvious way to write it is slow. Sorting every row by ST_Distance makes PostgreSQL compute the distance to every row in the table, then sort them all, to return five. PostGIS has an operator that lets the index do the ordering instead.

The <-> operator and a GiST index

<-> returns the distance between two geometries. Its point is that a GiST index can return rows already in order of that distance, nearest first, so a query with LIMIT 5 reads only a handful of rows from the index and stops:

CREATE INDEX places_geom_idx ON places USING gist (geom);

SELECT id, name
FROM places
ORDER BY geom <->
  ST_SetSRID(ST_MakePoint(-0.1276, 51.5072), 4326)
LIMIT 5;

Two conditions decide whether the index is used:

The operator has to be in ORDER BY. In a WHERE clause or a SELECT list it’s an ordinary distance function.
One side has to be fixed for the whole scan: a literal, a parameter, or a scalar subquery that returns one value. A column from another table in a plain join doesn’t count.

EXPLAIN shows which you got. The fast plan is an Index Scan using places_geom_idx with an Order By: (geom <-> ...) line under it. A Sort node over a sequential scan means the index isn’t doing the ordering.

That rule seems to rule out “the nearest hospital to each school”, but a LATERAL join gets around it. For each outer row, the inner query runs with that row’s geometry as a fixed value, so every inner scan is an index-ordered LIMIT 1:

SELECT s.name, h.name AS nearest_hospital
FROM schools s
CROSS JOIN LATERAL (
  SELECT name
  FROM hospitals
  ORDER BY hospitals.geom <-> s.geom
  LIMIT 1
) h;

One more trap sits in that first query: ST_MakePoint takes longitude first, then latitude. Coordinates pasted from a map are usually the other way round, and the query still runs, just somewhere else on the planet.

Geometry or geography

What <-> measures depends on the column’s type.

On geometry, it’s the planar distance in the units of the coordinate system. For longitude and latitude in SRID 4326, that unit is degrees, and a degree of longitude shrinks from about 111 km at the equator to nothing at the poles. Ordering by degrees is close to ordering by metres near the equator and increasingly wrong away from it, so the “nearest” row can be the second or third nearest on the ground. That includes the London query above.

There are two ways out:

A geography column. Distances are in metres. <-> on geography uses a sphere, which is fast and good for ordering. ST_Distance on geography uses the spheroid by default, which is more exact. Order with <->, and show ST_Distance when the number itself matters; the two can disagree slightly on near ties.
A projected geometry column in a metric coordinate system that fits the area, such as the local UTM zone. Planar maths is then both fast and accurate, as long as the data stays inside that area.

For data spread across a country or the world, geography is the simpler choice. For a city or a region, a projected geometry is the usual one.

ST_DWithin as a prefilter

“Nearest” with no limit on distance will happily return a place 800 km away when nothing is closer. Usually the real question is “the nearest few, within 5 km”. The tempting way to write the radius uses ST_Distance in the WHERE clause, which computes every distance again. ST_DWithin asks the same question in a way the index can answer, because it starts with a bounding-box test:

-- $1 is the search point, as geography; places has a GiST index on geog
SELECT id, name, ST_Distance(geog, $1) AS metres
FROM places
WHERE ST_DWithin(geog, $1, 5000)
ORDER BY geog <-> $1
LIMIT 10;

On geography the distance is in metres, and the spheroid is used by default. On a geometry column in SRID 4326 the same 5000 means 5,000 degrees, which covers the whole planet and filters nothing. It returns results, just not the ones asked for.

Sources: the PostGIS reference for <-> and ST_DWithin, and the PostGIS workshop’s nearest-neighbour chapter.