← Home
tens-city activitypub federation fediverse go

tens-city v0.8: A Federated Blog Without a Database

We released tens-city v0.8.0 in January 2026. It's a minimal blog platform with ActivityPub federation, and you can follow this blog from Mastodon at @myork@blog.stackdump.com.

Status, November 2026: tens-city no longer runs as a service of its own. This blog's own webserver (cmd/webserver in the blog's repository) imports its packages — activitypub, docserver, webmention, webserver — and that is where the code serves traffic now. The claims below were checked against the tens-city source in November; see What Changed at the end.

The Minimal Stack

Most blog platforms grow into content management systems — admin panels, user management, plugin systems, database migrations. We went the other direction.

The Minimal Stack

The entire stack:

Component Purpose
Markdown files Content with YAML frontmatter
Go binary Renders markdown, handles HTTP, signs ActivityPub requests
JSON files Followers, published posts
PEM file RSA signing key (data/activitypub.key by default)
nginx TLS termination, reverse proxy

No database server, no background job queue, no cache layer. The webserver reads markdown files from disk and renders them on demand.

ActivityPub Federation

ActivityPub is what this release added. The protocol is shared by Mastodon, Misskey, Pleroma and others; we wrote against Mastodon's documentation and have no record of testing against the rest.

ActivityPub Federation

When someone searches for @myork@blog.stackdump.com on Mastodon, their server queries our WebFinger endpoint (/.well-known/webfinger) for the actor URL, then fetches the actor profile for the inbox, outbox and public key. A Follow arrives as a Follow activity POSTed to our inbox; inbox.go checks that the object is our actor ID, appends the follower's actor URL to followers.json, and sends back a signed Accept. An Undo of a Follow removes the URL again. Publishing wraps a post in a Create activity with an Article object (outbox.go) and POSTs it to each follower's inbox.

HTTP Signatures

Everything we send is signed with our RSA key — the deliveries and Accepts, and also the GETs we make to fetch a follower's actor document for its inbox. httpsig.go signs POSTs over five headers, with a SHA-256 Digest of the body among them:

Signature: keyId="https://blog.stackdump.com/users/myork#main-key",algorithm="rsa-sha256",headers="(request-target) host date digest content-type",signature="base64..."

The receiving server fetches our public key from the actor profile and checks the signature over those headers; the digest is what ties it to the body. That makes our outbound traffic hard to spoof. The other direction is not covered: the inbox reads an incoming Signature header only to log it and does not verify it, so a Follow or Undo is taken at its word. The design notes we wrote before building it list inbound verification as a requirement, and it is still open.

State Without a Database

The follower list and the record of which posts have been federated are the state most platforms would put in PostgreSQL. We keep them in two JSON arrays next to the key file.

State Files

// followers.json (shape only; these accounts are placeholders)
[
  "https://example.com/users/someone",
  "https://example.org/users/another"
]

// published.json
[
  "https://blog.stackdump.com/posts/tic-tac-toe-model",
  "https://blog.stackdump.com/posts/token-language"
]

Every operation reads the whole array, changes it, and writes it back (publish.go, saveFollower in inbox.go). There are no transactions and no queries. For a personal blog's follower count that is plenty; we haven't measured where it stops being plenty, and the original claim here that it "scales to thousands of followers" was never benchmarked. The tradeoff we accepted knowingly is that we can't ask "who followed after date X" or "which posts got the most boosts", and the inbox doesn't record boosts anyway.

The Publish Workflow

Publishing a post is one command:

Publish Workflow

./publish.sh "Add new blog post"

This script:

  1. Commits changes to git
  2. Pushes to GitHub
  3. SSHs to the server and pulls
  4. Restarts the webserver
  5. Calls /publish to federate new posts

The federation step is safe to re-run: it checks published.json and skips posts already sent. The cost of that simplicity is in PublishPost — delivery is one goroutine per follower with no queue and no retry, and a post is marked published as soon as one delivery succeeds, so a follower whose server was down at that moment never gets it. (Since then, a push to main also deploys on its own: the blog's webserver carries a GitHub webhook that pulls, rebuilds and restarts. Federation still waits for the /publish call.)

What We Left Out

Most of the design is subtraction. There is no admin panel; posts are markdown files under git. There are no media uploads; images go in content/images/ and get committed. There are no comments on the page — replies happen on Mastodon and stay there, because the inbox acknowledges an incoming Create and drops it (the current code does receive Webmentions and shows the verified ones). There are no scheduled posts and no themes; the HTML and CSS are embedded in the binary, so changing them means forking. Analytics we did not leave out, though the first version of this post said we had: when GOOGLE_ANALYTICS_ID is set the docserver adds a Google Analytics tag, and this blog sets it. Each feature we didn't build is a maintenance burden we don't carry.

Running Your Own

# Clone and build
git clone https://github.com/stackdump/tens-city
cd tens-city && make build

# Configure ActivityPub
export ACTIVITYPUB_DOMAIN=blog.example.com
export ACTIVITYPUB_USERNAME=author
export ACTIVITYPUB_PUBLISH_TOKEN=$(openssl rand -base64 32)

# Start server
./webserver -addr :8080 -content content/posts

Add markdown files to content/posts/, put nginx in front with TLS, and you have a federated blog. The RSA key is generated on first start at data/activitypub.key unless ACTIVITYPUB_KEY_PATH says otherwise, and the two JSON files appear beside it.

Tent Cities

The name "tens city" is meant to evoke tent cities — minimal structures, easily moved, no bureaucracy. The software tries to match: a single binary, files on disk, nothing to run beside it but nginx. We could add user accounts, comment moderation, post scheduling, theme customization, and each would make the system harder to understand, maintain and trust.

The first version of this post said the whole ActivityPub implementation was ~500 lines of Go. Today pkg/activitypub is eight files and about 1,500 lines, roughly 1,100 without blanks and comments; we didn't re-count at the v0.8.0 tag, and the package has no tests of its own. It is still small enough to read in a sitting, which is the point — when something breaks we know where to look, and reading it is how we found the unverified inbox above. The argument is the software version of Small Models > LLMs.

What Changed

Revised 2026-11-15 against the tens-city source (pkg/activitypub, pkg/webserver, cmd/webserver) and this blog's publish.sh. Nothing was re-run.

  1. Inbound signatures. The post said we verify the HTTP signature on an incoming Follow. The inbox does not verify signatures; it logs the header. Said so, and noted the requirement is open.
  2. Signed headers. The example listed four signed headers; the code signs five (content-type too), and also signs outbound GETs.
  3. Size. Title and body claimed 500 lines. The ActivityPub package is about 1,500 lines today, and tens-city as a whole is several thousand; the title no longer makes a line-count claim.
  4. Analytics. "No analytics" was wrong for this blog: a Google Analytics tag is added when its ID is configured, and it is.
  5. State. The RSA key is a PEM file, not JSON. "Scales to thousands of followers" was never measured; hedged. Delivery has no retry, and a post counts as published after one successful delivery.
  6. Status. tens-city no longer runs on its own; this blog's webserver imports its packages.
×

Follow on Mastodon