One backend is one deployment

The first instinct is to run a single Convex backend and point all three apps at it. That doesn't work. A Convex backend serves exactly one deployment. Three apps with different schemas would collide on day one — one has workspaces and captures, another has plateCache and dvsaToken, and they'd be sharing a table namespace.

So it's one backend per app. They can still share a Postgres server, because Convex derives its database name from INSTANCE_NAME, swapping hyphens for underscores:

ripplebug:
  image: ghcr.io/get-convex/convex-backend:latest
  environment:
    - INSTANCE_NAME=ripplebug
    - POSTGRES_URL=${POSTGRES_URL}

Three of those, three databases, one Postgres container. Each backend idles around 30 MB, so separating them costs nothing worth counting.

The part that bites

convex export carries data only. It does not carry your deployment's environment variables.

That's obvious in hindsight and invisible at the time, because everything looks fine. The data's there. The dashboard loads. Functions deploy. And then nobody can sign in, because JWT_PRIVATE_KEY and JWKS never came across, and without them Convex Auth can't mint or verify a session.

The failure is silent in the worst way. It isn't a line in a log, it's a login page that just doesn't work. On one app alone, sixteen variables were still sitting on the old deployment: auth keys, Stripe price IDs, a Resend key, an OpenAI token.

Copy them across explicitly:

npx convex env list                    # against the cloud deployment
npx convex env get NAME                # one at a time
CONVEX_SELF_HOSTED_URL=... npx convex env set NAME value

Two traps in that last command. Values that start with - — a PEM key, some secrets — get parsed as CLI flags, so you need convex env set -- NAME value. And multi-line values truncate at the first newline if you set them from Windows, because argv doesn't survive it. Set those from the server.

What it actually costs

Three backends, one Postgres, behind a reverse proxy that was already running. Idle memory for the whole set is under 200 MB. The deploy pipeline changed by one variable — CONVEX_DEPLOY_KEY becomes CONVEX_SELF_HOSTED_URL plus an admin key — and CI didn't otherwise care.

Honest summary: the migration is easy, the environment variables are the entire difficulty, and you want to have checked them before you cancel anything.

The spinning circle doesn't appear when it stops, like it normally does when the internet drops.

That sentence is the whole diagnosis, and it took me an embarrassingly long time to hear it.

What a spinner actually means

A buffering spinner means the player asked for data and is waiting. There's a request open. The network might be slow, the server might be slow, but the conversation is still going.

No spinner means the player isn't waiting for anything. It either got an answer it couldn't use, or it stopped asking. Those are different failures in different halves of the system.

Here are both, side by side. Hit play and watch which one spins.

I spent the first hour checking everything a spinner would have implicated: server load, disk I/O, network errors, bandwidth. All clean. Load average 0.14, zero packet loss, and a sustained pull of 1.3 GB at 63 MB/s without a single stall.

None of it mattered. The symptom had already ruled that half out.

The actual cause

The player was streaming HLS, which chops video into numbered segments. A cleanup job I'd scheduled was deleting those segments every four hours, including while someone was watching.

So the player asks for the next segment and gets a 404. Not slow data — no data, immediately, with an answer. Nothing to buffer, nothing to spin for. Playback just stops until the server notices and starts producing segments again from that position. That's the pause, and then the restart.

The fix was two settings that should have been on from day one:

• Throttling — the encoder pauses once it's far enough ahead, instead of racing to transcode a whole film as fast as the CPU allows.
• Segment deletion — old segments get dropped as playback moves past them, so the cache stays small by design instead of needing a sweep that can collide with someone watching.

With both on, the cleanup job has nothing left to clean up mid-stream.

The lesson I keep relearning

Every instinct I have points at throughput. The person reporting it had already told me it wasn't throughput. I checked anyway. Twice. Because throughput is what I know how to measure.

People using your software hand you the deciding detail without knowing it's the deciding detail. That one sentence contained a fact none of my monitoring had: the client wasn't waiting. No dashboard I own would ever have shown me that.

Writing a post

Make one file in blog/_posts/:

---
title: The thing I want to say
date: 2026-08-14
topic: engineering
summary: One or two sentences. This shows on the index and in search results.
---

Write the post here in Markdown.

Then push. That's the workflow.

title, date and summary are required. topic is one of product, engineering or tech, and it decides which accent colour the post carries. Add draft: true to keep something out of the build while you're still working on it.

There's a _TEMPLATE.md next to the posts with the front matter already filled in and the house rules in comments, so starting a post is a copy rather than a blank page.

What happens on push

GitHub Actions runs scripts/build-blog.mjs, which:

• renders every post to static HTML;
• rebuilds the index, newest first;
• writes feed.xml so the blog works in a reader;
• updates the blog's block in sitemap.xml and llms.txt;
• deletes generated pages whose source file has gone.

Then validate-site.mjs checks that nothing points at a missing asset or route, and only after that does Cloudflare Pages get the deploy. A broken link fails the build rather than shipping.

Why there's a build step at all

The rest of this site has no build step, on purpose. Pages are hand-written HTML. A blog is where that rule stops paying for itself.

Hand-writing each post means editing three or four files every time: the post, the index, the sitemap, the feed. That decays fast. It's the reason so many company blogs have four posts and a last-updated date from two years ago.

The trade here is that the output stays exactly as static as everything else. No client-side rendering, no service to go down. A crawler and a reader both get finished HTML. The build step buys authoring convenience and spends nothing that mattered.

Two bits worth stealing

Managed blocks in shared files. The generator only writes between <!-- blog:start --> and <!-- blog:end --> markers in sitemap.xml and llms.txt. It never rewrites those files wholesale, so hand-written entries elsewhere in them survive every regeneration.

Deleting orphans. If a source file disappears, its generated directory goes with it. Otherwise unpublishing something leaves a live page that nothing links to and everything still indexes.