Self-hosting
Enabling federation
Turn on ActivityPub, in the right order, and confirm your instance is really federating.
Federation is off by default, so a fresh instance is a private, standalone blog. Turning it on lets your posts travel the fediverse and lets people on Mastodon and elsewhere follow your writers.
Order matters
Federation binds your server’s identity to your domain at startup, so:
-
Set your public domain first — in the wizard or Admin → Instance — and confirm HTTPS works at
https://your-domain. Federation effectively requires HTTPS; other servers will refuse plain HTTP. -
Turn on the Federation toggle in Admin → Instance (or set
FEDERATION_ENABLED=truein.env). -
Restart so the change takes effect:
docker compose up -d
Confirm it is active
On the server:
curl localhost:8000/version # -> "federation": true
Publicly:
curl https://your-domain/.well-known/nodeinfo # -> a links array
curl https://your-domain/nodeinfo/2.1 # -> software, version, usage
A 404 on either means federation is still off. The backend also logs
Federation enabled (ActivityPub) on boot.
The first of those is what fediverse directories fetch, so a working answer is also how the instance gets listed — see NodeInfo.
Finally, the real test — search for @yourusername@your-domain from a Mastodon
account and follow it. You should see the follow appear, be auto-accepted, and
your next published post arrive in that account’s timeline.
What turning it on changes
- Each local account becomes an ActivityPub actor with an inbox and outbox.
- Inbound
Followactivities are auto-accepted (unless the account requires approval for followers). - Publishing a post enqueues delivery to every remote follower’s inbox.
- Your instance answers WebFinger, host-meta, actor, followers, outbox, and NodeInfo requests. See ActivityPub endpoints.
- It becomes visible to fediverse directories — FediDB, instances.social, fediverse.observer. They read NodeInfo, which publishes aggregate counts only: accounts, sign-ins in the last 30 and 180 days, published local posts, and responses.
- Each account gains a second, machine-facing address at
/users/{username}alongside its/@{username}profile page. - The federation inbox becomes a public, unauthenticated POST endpoint — rate-limited per source IP and capped in body size.
- The instance starts caching the Omicron network in the background, and contacts the FediDB directory once a day. See below.
The federation network (auto-cache)
Without help, the Global feed only carries remote posts someone here already looked up, followed, or saw boosted, so a new instance’s Global feed starts almost empty. The auto-cache network fills it ahead of your readers.
Admin → Federation → Federation network lists the tracked instances. They come from two places:
| Source | How it gets there |
|---|---|
| FediDB | Once a day, every Omicron instance listed by FediDB is added |
| Added by hand | You type a domain into Add instance |
Each tracked instance is synced every 6 hours by default:
- Its NodeInfo is read to confirm it runs Omicron.
- Its public local feed is read only to learn who has written recently, up to 20 writers by default.
- Each writer is resolved over ActivityPub, and up to 20 of their latest public long-form posts (Articles) are cached. Short notes from other software are skipped.
Posts are never copied from the other instance’s API. They are fetched the same way as when a reader opens a remote profile, so they go through the same checks: only public posts, only from the author’s own server, and never from blocked domains or accounts.
| Setting | Default | Range |
|---|---|---|
| Auto-cache the network | On | — |
| Discover Omicron instances on FediDB | On | — |
| Sync every (hours) | 6 | 1–168 |
| Writers per instance | 20 | 1–100 |
Settings apply live, with no restart. Turning Auto-cache the network off stops both syncing and discovery.
Each instance row shows its status, its NodeInfo summary, how many accounts and posts are cached from it, and when it last synced and will sync next:
| Status | Meaning |
|---|---|
| Syncing | A sync of this instance is running now |
| Waiting | Not synced yet |
| Synced | The last sync worked |
| Other software | Not Omicron. Writers can’t be discovered there; follows and replies still federate normally. Rechecked weekly. |
| Failing | The last sync failed. The error is shown, and retries back off up to once a week. |
| Skipped | The domain is suspended or limited under Domain blocks |
| Paused | You switched it off |
- Pause an instance with its switch. A paused FediDB instance stays paused: discovery never turns it back on.
- Sync now syncs one instance immediately.
- Only instances added by hand can be removed. A FediDB instance would be added back by the next discovery run, so pause it instead.
- Check FediDB now runs discovery immediately. If FediDB is unreachable the error is shown and discovery retries within the hour; tracked instances keep syncing.
Cached content still ages out under
REMOTE_CACHE_RETENTION_DAYS once an instance stops
being synced.
What it does not change
- Unpublished posts are never federated. Only published posts are delivered — a draft or a post waiting for its scheduled time is not, and a scheduled post federates when it goes live, not when it is scheduled.
- Private accounts still gate their followers — approval is enforced before anything is delivered.
- The API and your reading experience are unchanged.
Turning it back off
Flip the toggle and restart. The ActivityPub code paths stop being loaded entirely. Remote followers will simply stop receiving deliveries; they are not notified, and their follow records remain on their side.
Moderation across instances
Once you federate, you inherit the wider network’s problems. Two tools:
- Admin → Federation suspends or limits a domain, and blocks single remote accounts.
- Admin → Reports is the moderation queue for user-reported posts and actors, local or remote.
See Moderation tools.
Deliverability notes
- Delivery runs through a queue, so a slow or down remote server never blocks a user’s request. With Redis configured, pending deliveries survive a restart.
- Fedify handles HTTP signatures and retries.
- A remote server that has blocked your domain will reject deliveries; that is their decision and there is nothing to fix on your side.
Found a mistake?Edit this page on GitHub.