ブログ『洪民憙雑記』をPHPからAstro + Netlifyに移行して、ついでにFedifyでActivityPubに対応させた話を文章にまとめた。
writings.hongminhee.org
I added ActivityPub to this blog
I built this blog with Jikji, a static site generator I wrote myself, almost five years ago. Back then I barely knew TypeScript or modern web tooling, and I'd…
I built this blog with Jikji, a static site generator I wrote myself, almost five years ago. Back then I barely knew TypeScript or modern web tooling, and I'd…
I added ActivityPub to this blog
I built this blog with Jikji, a static site generator I wrote myself, almost five years ago. Back then I barely knew TypeScript or modern web tooling, and I'd never implemented ActivityPub. TypeScript and modern web tooling are second nature to me now, and ActivityPub has become central to my work. I maintain Fedify, for whatever that's worth, and it bothered me that my own blog wasn't federated. So I fixed that.
The old stack: Jikji and PHP
This blog used to run on Jikji, a static site generator I wrote myself in
Deno. Calling it a static site generator is a bit of a stretch, though.
Like old Movable Type installations, it didn't just produce HTML; it
generated a bit of PHP too. That PHP existed almost entirely for HTTP
content negotiation: it read the browser's Accept-Language header and
chose among Korean mixed script, hangul-only Korean, English, and
Japanese. That's all it did.
I first considered adding a thin ActivityPub implementation directly in
PHP, since I was already using it. But I wasn't really writing that PHP by
hand; Jikji generated it for me, and I had no interest in hand-coding PHP
myself. Federating meant delivering a Create(Article) activity to
followers whenever a new post went up, which meant I'd need something like
a message queue. Bolting a message queue onto Jikji's generated PHP felt,
to me at least, like more complexity than it was worth maintaining. And
honestly, with Fedify already around, I had no desire to implement
ActivityPub from scratch again.
So I ripped out PHP entirely and decided to bring in Fedify instead.
The new stack: Astro and Netlify
The first decision was to drop Jikji and PHP for Astro, a JavaScript framework built for static-content-heavy sites. I chose Astro largely because it already had a @fedify/astro integration.
I reused as much of the existing CSS and HTML as I could. I'm happy with the current design, and redoing it alongside everything else felt like scope creep waiting to happen. Permalinks stayed exactly as they were. I wanted to replace the stack underneath without visitors noticing anything had changed at all.
For hosting, I went back and forth between Cloudflare Workers and Netlify,
and settled on Netlify partly because Fedify had never run there before,
and this seemed like a good excuse to add that support. I've hosted
static sites on Netlify plenty of times, but this was my first time
pairing it with edge functions. The idea of a mostly static site with a
few dynamic slices reminded me of the late-nineties web, when a site was
static HTML except for whatever lived in /cgi-bin/.
Publishing used to mean committing a Markdown file to Git, pushing, letting GitHub Actions build the static site, and deploying it over SFTP. Now GitHub Actions is out of the build pipeline entirely, since Netlify builds the site itself. It ended up simpler overall.
I'm happy with Astro, and the migration went smoothly. It beats Jikji, which I'd barely touched since building it five years ago. Jikji is now archived; there's no reason left for me to keep maintaining it.
Fitting Fedify into Astro
Updating @fedify/astro
Once I actually tried to add Fedify to Astro, I ran into a problem: @fedify/astro didn't support Astro 7, the current version. The Astro APIs it relied on hadn't changed much internally, but the package's declared compatibility range, and its tests, only went up to Astro 5. So before I could federate the blog, I had to fix @fedify/astro first.
That meant more than widening a version range. The existing tests built a
fake Astro context and called the middleware directly, which couldn't
catch problems with Vite's SSR configuration, compatibility across
adapters, or request routing on a built server. So I wrote new
compatibility tests that pack @fedify/astro for real, install it into a
small Astro app, build and start the app, and send real HTTP requests to
it.
Those tests check, across Astro 5, 6, and 7, that HTML requests reach
Astro's pages, that ActivityPub and WebFinger requests are handled by
Fedify, and that Astro's 404 Not Found still applies to everything else.
For Astro 7 specifically, I also run the tests against Deno and Bun, not
just the Node.js adapter.
That work has already been merged upstream and will ship in Fedify 2.4.0.
Static pages, dynamic endpoints
The Astro project as a whole builds with server output, but the existing
blog pages are still prerendered, same as before. WebFinger, the actor,
the inbox and outbox, the followers collection, and ActivityPub objects
are the exceptions: Fedify handles those dynamically, per request. The
middleware @fedify/astro provides looks at a request's URL and Accept
header and only intercepts what Fedify is meant to handle. The same URL
can return the existing Astro page for an HTML request and a Fedify-built
object for an ActivityPub one.
What visitors see is still, for all practical purposes, a static site. Nearly all the new dynamic surface lives somewhere only other fediverse servers ever touch. That's the CGI comparison again.
Person and Article
Adding ActivityPub also meant deciding what counts as an actor here, and
what counts as an object. I gave the blog's actor a Person type.
Publishing itself is automated, but the actor represents me, the person
writing these posts, not a piece of software or a service. So the handle
is @hongminhee@writings.hongminhee.org, and the actor's web URL points at
the blog.
Each post gets an Article. It has a title and a body, and it lives at
its own permalink as a long-form document, which fits Article better
than Note. Most major ActivityPub implementations support Article
these days, Mastodon included. Human-facing permalinks stayed put;
ActivityPub objects got their own URIs instead, shaped like
/ap/articles/{year}/{month}/{slug}. Article's url points back at the
original permalink, so the object's identity and the web page people
actually read stay separate.
Multiple languages took more thought. Representing each language as its
own Article would scatter likes and shares for the same post across
several objects. So I merged the Korean mixed script, hangul-only Korean,
English, and Japanese versions under a single Article, all sharing one
permalink. Title, summary, and body each carry language-tagged values for
every version, which serialize to JSON-LD as nameMap, summaryMap, and
contentMap. For implementations that don't handle per-language values,
name, summary, and content also carry a default: English if there's
an English version, Korean mixed script otherwise. Each language's HTML
page also gets a Link on Article's url, tagged with hreflang.
That way, a receiving server that understands multiple languages can pick a title and body matching the reader's language, and one that doesn't can still fall back to the default. In practice, though, I know of hardly any ActivityPub implementation that renders these multilingual values properly yet. There's an open issue for it on Mastodon's tracker, and a similar proposal on Hackers' Pub's, but neither has a timeline. Some of that is probably a UI design problem as much as anything else.
Running Fedify on Netlify
Unlike serving plain static files, an ActivityPub server needs some state that outlives any single deploy. The actor's signing key can't rotate on every deploy. The followers list can't disappear on the next one either. Both live in Netlify Database.
Incoming and outgoing activities go through a message queue built on Async Workloads. Delivery can be slow or fail outright depending on the receiving server, so it can't all happen inside the function handling the HTTP request. Queuing it separates accepting a request from actually delivering it, and failed deliveries can be retried later. Fedify already abstracts this, with pluggable backend adapters, but there wasn't yet an adapter for Netlify's Async Workloads. So I wrote the @fedify/netlify package, which uses Async Workloads as the queue and keeps delivery-order state in Netlify Database.
Announcing new posts to the fediverse turned out to be a separate problem.
A static site finishing its build doesn't tell a running ActivityPub
server anything about which posts changed. So on every successful
production deploy, I diff the current post list against the previous
deploy's. New posts get a Create(Article); edited ones, whether the
content or just the timestamp changed, get an Update(Article); removed
ones get a Delete(Article). All of it goes out to followers. Retries
reuse the same activity ID for the same change, and deploy ordering is
checked so that an older deploy syncing late can't undo a newer one.
Netlify's deploy previews and branch deploys have federation turned off entirely. Otherwise every preview would spin up an actor claiming to be this same blog, and a test deploy could end up sending activities to real followers. Locally, I develop against an in-memory store and queue; production is the only place using the persistent database and queue.
Fedify now runs on Netlify Functions, alongside Deno Deploy and Cloudflare Workers, on top of its usual support for Node.js, Deno, and Bun.
Wrapping up
None of this gives the blog a timeline, a reply box, or any other social
feature. Writing and reading still work the way they always did, and the
permalinks and design are basically untouched. What changed is that the
blog, and every post on it, now has a name and address the fediverse
understands. Follow @hongminhee@writings.hongminhee.org to get new
posts, or look up a post's ActivityPub object URI to find the original.
I've maintained Fedify long enough to show other developers how to implement ActivityPub, and I dogfooded it plenty while building Hollo and Hackers' Pub. But this was the first time I'd added it to a site that was already live, and static at that. Along the way I got a compatibility test suite for the Astro integration, Netlify support, and a handful of deployment and operational problems that no amount of reading docs or unit tests would have surfaced. It turns out Fedify isn't just for building new social networks from scratch; it works just as well for bringing an existing site into the fediverse without changing how it looks.
hackers.pub
