CommonPub: In-depth Explainer
An open source, self hosted, ActivityPub native platform for maker communities. Hubs, contests, events, learning paths, docs, and product catalogs that federate with the rest of the fediverse. Own your community. Federate everything else.
Who actually owns your community?
The platform you pick decides how much of your community is really yours. A Discord server lives or dies on Discord's whims. A subreddit can be quarantined overnight. A Patreon page can be deplatformed for content the platform changes its mind about.
CommonPub is the other shape. The database is on your VPS. The source is AGPL 3.0 or later. The federation protocol is an open W3C standard. Flip between the two pictures.
Owning the box only matters if it talks to the rest of the world. The next question is what kind of plumbing makes that possible.
What is a federation, really?
You already use a federated system every day. It is called email. Someone on gmail.com can send a message to someone on outlook.com, and neither service has to ask the other for permission. Each server is independent, but they all speak a shared protocol (SMTP).
Now imagine that for communities: hubs, posts, events, build logs, learning paths, all flowing between independent servers. That shared language exists, and it is called ActivityPub.
ActivityPub is the protocol. Now look at what CommonPub builds on top of it: the packages that turn the protocol into a working community platform.
What is actually in the box?
CommonPub ships as twelve composable TypeScript packages on npm, plus a shared Nuxt layer (@commonpub/layer) that wires them together. The packages rest on two foundations: @commonpub/schema (79 Drizzle tables, 41 enums) and @commonpub/config (defineCommonPubConfig with 16 feature flags). Every other package builds on those two.
Flip each card to see what the package does. You do not have to take all twelve. A docs only site can use @commonpub/docs. A standalone explainer host can use @commonpub/explainer. The layer is where they cooperate.
Twelve packages and one layer is the code. But code is just the engine. What does the product actually look like once it is running?
What surfaces does an instance ship with?
Out of the box, a CommonPub instance gives you the surfaces a real maker community actually uses, not just a feed. Each surface is a feature flag away, and each one federates over ActivityPub when other CommonPub instances follow you.
Click a card to expand it. These are the surfaces, not the underlying packages.
Surfaces are what your members see. The next question is what you actually have to maintain to keep them running.
What does a deployed instance actually look like?
This is the part that usually scares people off self hosting. How big is the app, how much will I have to maintain? CommonPub's answer is a pattern called the thin app.
A deployed instance is roughly four files plus an env file. nuxt.config.ts extends @commonpub/layer. commonpub.config.ts sets your feature flags. server/utils/config.ts resolves env and DB overrides. components/SiteLogo.vue is your brand. Everything else (86 pages, 106 components, 283 API routes, the 79 table schema) lives in the layer and updates with pnpm update.
Deployment paths: Docker Compose on a VPS with Caddy auto TLS, DigitalOcean App Platform with their app-spec.yaml, App Platform plus managed Postgres (DO or Supabase), or any Docker host using the multi stage Dockerfile at the repo root. The reference instance at commonpub.io runs on a single DO droplet. deveco.io is ~25 thin app files over the layer.
Schema migrations ship as committed SQL in packages/schema/migrations/. scripts/db-migrate.mjs runs them idempotently on every boot. You never run drizzle-kit push in CI, and you never apply SQL by hand.
Four files, a layer, Postgres, and AGPL. That is the whole production picture. So if you are going to contribute to that layer, what are the rules of the road?
How do you avoid building it wrong?
CommonPub has strong opinions, and they are easy to violate by accident. The conventions exist because they keep features federation safe, theme safe, and upgrade safe. The short list looks pedantic until you have watched a community owned site get repainted because someone hardcoded a hex code.
- Start every feature with the right tables in @commonpub/schema. The schema is the contract; the code follows.
- Gate every non core feature behind a flag in commonpub.config.ts. Admins should be able to turn features on and off without redeploying.
- Use var(--color-*) tokens for every color, font, and spacing value. Themes (base, dark, generics, agora, agora dark) just remap tokens.
- Ship SQL migrations as committed files in packages/schema/migrations/. Boot runs them idempotently.
- Skip the schema and bolt features onto random tables. Federation, search, and migrations will all break later.
- Hardcode a feature on. Admins lose runtime control, and forks lose the ability to opt out of features they do not want.
- Hardcode a hex color or font family. Themes will silently break and the next contributor will quietly hate you.
- Run drizzle-kit push in CI or apply SQL by hand on a deployed DB. Drift between environments is the path to data loss outages.
Conventions are guardrails, not chains. Before we wrap, one quick check: do you remember the thing that makes CommonPub different from a plain Mastodon server in the first place?
What does CommonPub federate that Mastodon can't?
Mastodon federates microblog posts: a username, a short text, maybe an image. That is powerful, but a maker community needs more.
A build log with a bill of materials. A contest with judging rounds. A learning path with quizzes and certificates. An event with RSVPs and a waitlist. A versioned docs site. An interactive explainer (like this one).
CommonPub federates all of that using a typed block system called BlockTuple, mapped onto ActivityPub. A Mastodon user sees a readable article. Another CommonPub instance gets the full structured experience.
That is the whole picture: federation, packages, surfaces, deploy, conventions. Here is what to do with it.
Your community, your data, your stack, talking to everyone else's.
Federation is the protocol layer. Twelve packages and a Nuxt layer are the code layer. Hubs, contests, events, learning paths, docs, explainers, and a BOM linked product catalog are the surface layer. Schema first, flag gated, token themed, migration disciplined: that is the house style that keeps it all upgradeable.
The whole stack is AGPL 3.0 or later, sits on Postgres 16 with no proprietary services, and fits on a $6 VPS. The reference instance is commonpub.io. A real branded fork is deveco.io at roughly 25 files over the layer.
If you run a maker community (a hackerspace, a contest series, a learning collective, a parts ecosystem), CommonPub is what "owning your platform" actually looks like in 2026. Spin one up with cargo install create-commonpub and create-commonpub new my-community, or read the source and the architecture decisions in the repo.