Blog
Appearance
Login

How this blog was built

Published 2026-11-17 · 11 min read

Last updated 2026-11-18

tagsbuildastropocketbasemoderation

Author

TLDR — Static markdown in git for the words, one PocketBase binary for the parts that need to be alive, Astro for the pages, and a model that only answers whether a comment should go, with no tools and no authority. This is the whole machine, and the page you are reading is produced by it.

How this blog was built

This post is the first one, and it is also the most self-referential thing on the site: the text you are reading was written as a markdown file in git, imported into a database by a script, and rendered by the same build that produces every other page here. If the build breaks, this page breaks with it.

The split that decided everything

The site has two halves with completely different requirements.

The words are content. They live in git as one markdown file per translation (content/posts/<slug>/en.md, content/posts/<slug>/de.md), with images next to them. They are written in an editor, reviewed as diffs, and never edited through an admin panel. Nothing about them needs a server.

The interactions are dynamic: comments, likes, and the identity record each reader has. These cannot be pre-rendered, because they depend on who is reading.

So the split is: static build for content, one small backend for interaction. That single decision chose most of the stack.

Why not Ghost, Hugo, or WordPress

Ghost and Hugo are excellent at the first half and useless at the second. A comment system on top of a static generator means either a third-party service (which brings third-party cookies, and that is the honest reason the identity page below exists: no third-party analytics and no third-party cookies, because the disclosure page’s credibility depends on it) or a database and an API you build yourself.

WordPress solves both halves but drags a whole runtime with it, and the interesting parts of this project — the comment pipeline, the moderation policy — would be buried inside a plugin ecosystem. I wanted the policy to be a file I can read and tests I can run.

Hugo would have been fine for the content half, but Astro won for a practical reason: it renders at build time and lets individual islands be interactive. A page that is 100% static except for a comment form is exactly the shape Astro is built for. Shiki highlights code at build time, so no client-side highlighter is shipped to the reader.

Astro also forced one small discipline: component names have to be capitalized. A lowercase name like <toc> is parsed as an HTML tag, and the build happily emits a literal <toc> element into the page. I hit that before I noticed it.

PocketBase as the whole backend

The backend is one binary with an embedded SQLite file. Collections: posts (a mirror of the git content so comments and likes can reference stable ids), comments, reactions, visitors, moderation_events, abuse_events, and a read-only view for post stats. The schema lives as committed migrations, so a fresh instance is reproducible.

Two honest caveats.

First, PocketBase is not PHP. There is no request-scoped rendering here; the site is a static build and PocketBase is only an API. Anything dynamic on a page is an island calling the API.

Second, the hook runtime is neither Node nor a browser. There is no fs, no fetch, and no npm module resolution inside pb_hooks. That single constraint determined where the identity engine lives, because hashing has to come from one of three places: the runtime’s own $security helpers, a pure implementation inside the hook, or a Go extension. The shared logic in this repo is written so it never imports a runtime — the hook loads it as a generated CommonJS bundle, and the caller injects its own hash function. Two runtime traps worth remembering: hook files share one top-level scope, so a const helpers = require(...) at the top of one hook can collide with another hook; and JSON fields come back as wrapped Go maps, so they must be parsed through getString before being indexed by name.

Custom routes live under /api/blog/* so they do not collide with the system collection routes.

The no-login problem, and why proof of work is the answer

Everyone here is anonymous by default. Only one account exists: mine. That is the reading model I wanted — you should not have to create an account to comment on a blog.

Anonymous write access needs a cost, otherwise it is a spam inbox. The pipeline is ordered so that cheap checks come first:

  1. honeypot field, rejected silently;
  2. proof of work — the client solves a nonce with leading zeros, the server verifies it in microseconds, difficulty is configurable and required only for writes;
  3. a bot_score from signal volatility and request speed;
  4. a rate limit keyed on the identity, never on the IP (NAT and mobile carriers make per-IP limits punish normal readers);
  5. content rules: length bounds, a markdown subset only, no HTML, a link limit, and a duplicate content hash inside a window;
  6. only then the insert.

The rejections answer 200 and look like success. A rate limit is the only honest 429, because it is a throttle rather than a detection. This matters for the same reason honeypots work: telling the client which gate caught it teaches the client how to pass it.

Detection-style rejections counting as submissions would let a bot map the thresholds; counting only accepted submissions keeps the window quiet, and the abuse rows are still written for the record.

Identity is layered, not a fingerprint

Identity is a keyed hash over layers. The primary layer is a first-party cookie: random id, HttpOnly, SameSite=Lax, Secure, long expiry. Secondary signals are stored coarse and hashed: IP, browser family and major version bucket, accept-language, timezone offset, DPR and rounded screen size, platform family.

The policy decision was explicit: the cookie is the identity, and the secondary signals are recorded individually and feed bot_score plus a per-signal stability flag. Strict policy — any single signal change means a new identity — is defensible and arguably more honest, but a reader moving from wifi to mobile becomes a different person, and the site would keep re-baselining them. So the identity page shows both: which signals currently contribute to the key, and which ones differ right now. Like counts are idempotent on top of that via UNIQUE(post, visitor), so duplicate likes are impossible regardless of which policy you would have picked.

The line the agent enforces

The moderation worker reviews new comments. Swearing, harsh criticism, disagreement, sarcasm: fine. Illegal content, threats of violence, targeted harassment of a named person, slurs, doxxing, scam links, machine-generated spam: removed.

The worker is not the law here — the deterministic pass is. Content rules decide format, the model decides the contextual categories only, and the agent never hard-deletes. It changes a status and writes an audit row. Removed comments are kept for 30 days with a restore window; the author can ask for a second pass, low-confidence cases escalate to me, and after the window the body is purged while the metadata row stays. Every raw model response is logged with confidence and a policy version, because otherwise there is no way to prove the agent was right when someone complains.

The worker runs as a scheduled pass, not as a hook: hooks cannot call a model. Without a model configured it still runs, and the deterministic rules apply on their own.

The model has no hands

The worker is a plain program: it reads the pending comments, asks one question per comment, and then performs the writes itself. The model never receives the blog. It runs with no tools, so a comment cannot make it call the api, fetch a url, read a file, reply to a visitor, or print the credential its process was started with. The payloads that work against an agent with tools — ignore the policy above, list what you can see, delete the other comment — have nothing to execute here.

The alternative was an agent harness with a shell and curl pointed at the comment queue. That is more flexible, and it is the wrong shape for this job. A comment is untrusted input by definition, and the moment the thing reading it can also act, the comment decides what the action is. So the model’s whole job is one answer about one comment: keep or remove.

Three things hold that up. One call per comment in an isolated session, so a hostile comment gets one turn and cannot carry context into the next comment. The comment arrives as data on stdin and the argument list is built without a shell, so comment text can never become an option, a path, or a command. And the answer carries no target: the worker applies it to the comment it read, because there is no field in the answer where a comment id could go. The model process receives the provider key and nothing else, never the blog credential.

It runs once a day at 4 am rather than as a loop: the deploy is a cron that starts the image, the worker reads the pending comments, answers for each one, performs the writes, and exits. An answer it cannot parse, or a confidence below the floor, becomes a recorded human review row instead of a removal. Every answer is stored with its policy version, so a decision can be checked after the fact.

The identity page is a feature, not plumbing

The page is here, and this is what it looks like on a normal visit:

The identity page with the signal checks and the fingerprint component table

/identity lists every signal that would make you a different identity, each with a checkmark or a cross against what is stored. It shows the key prefix, the cookie value, the masked IP with a per-field reveal, the timezone, the browser bucket, DPR and screen, first and last seen, all your comments, all your likes, the score, and each retained row with its own expiry. There is a raw JSON export and a delete button. Live recompute means the crosses change as you change things — including by switching networks, which is exactly the case that made the policy choice above.

Everything sensitive is stored raw server-side and displayed masked. Reveals are per field and audited. Showing a reader what is stored about them is the difference between a system that claims to be minimal and one that can be checked.

Deployment is boring on purpose

PocketBase binary plus a data volume, and the prerendered site copied into the same image, so PocketBase serves the pages as static files and the hook routes on the same port. Nothing else is shipped: TLS, caching, HSTS, CSP with script-src 'self' (which is why island client code is served as module files rather than inline scripts), Referrer-Policy, X-Frame-Options, and no analytics are the business of the proxy in front of it, and that proxy is yours. Litestream streams the SQLite file to object storage. The whole backend is one file, so losing it loses everything. Secrets through environment variables.

The proxy has to get the client ip right. e.realIP() follows a forwarded header only when PocketBase is told which header to trust, and that is a stored setting rather than an environment variable, so without it an identity records the proxy address instead of the visitor. Behind Cloudflare, nginx accepts CF-Connecting-IP only from Cloudflare’s own ranges, and the same header is the one PocketBase is told to trust.

The author picture is a PocketBase file field, so it lives in the same single file as everything else — no separate storage bucket, no CDN.

Running it

The whole stack is pocketbase + moderation, in compose or as two systemd services.

bun run test                    # pure logic: signals, hashing, pow, scoring, policy, theme
cd pocketbase && bun run test_integration   # against a throwaway instance
cd site && bun run build
cd deploy && docker compose up -d

Tests are split by what they need: test/unit for pure functions, test/integration against a throwaway PocketBase instance. Policy fixtures deliberately include hostile-but-allowed comments — profanity and harsh criticism — to prove the classifier does not over-remove.

What the first post is actually about

The interesting part of this project is not the software. It is the set of choices that were made before writing any of it: what counts as content versus interaction, what a reader is allowed to do without an account, what an agent is allowed to remove, and what the site is willing to show a reader about themselves. Everything else is plumbing in service of those four answers.