January 1, 2025

Federation Guide

Rox is built on the ActivityPub protocol, allowing it to communicate and exchange content with thousands of other servers in the Fediverse (Federated Universe).

How Federation Works

When a user on your Rox instance follows a user on another server (e.g., mastodon.social), the servers exchange messages to:

  1. Subscribe: Your server asks the remote server to send updates.
  2. Deliver: When the remote user posts, their server pushes the activity to your server's Inbox.
  3. Process: Your server processes the activity and adds it to your user's timeline.

Supported Activities

Rox supports the following ActivityPub activities:

  • Create (Notes/Posts)
  • Delete (Notes)
  • Follow / Undo Follow
  • Like / Undo Like
  • Announce (Renote/Boost)
  • Update (Profile updates)

Configuration

Federation is enabled by default but can be configured in your .env file.

Basic Settings

# Enable/Disable Federation
FEDERATION_ENABLED=true

# Shared Inbox (Recommended for performance)
SHARED_INBOX_ENABLED=true

Allow/Block Lists

You can control which instances your server communicates with.

# Allow List (If set, only these domains are allowed)
FEDERATION_ALLOWLIST=mastodon.social,misskey.io

# Block List (These domains are blocked)
FEDERATION_BLOCKLIST=spam-instance.com,bad-actors.net

Discovery

WebFinger

Rox implements WebFinger (RFC 7033) to allow users to be discovered by their handle (e.g., @[email protected]).

Endpoint: /.well-known/webfinger?resource=acct:[email protected]

NodeInfo

Rox provides NodeInfo metadata to help other servers and crawlers understand your instance's capabilities and software version.

Endpoint: /.well-known/nodeinfo

Troubleshooting Federation

"Remote user not found"

  • Verify the handle format: @[email protected].
  • Check if the remote instance is online.
  • Ensure your server can make outbound HTTPS requests.

"Posts not arriving"

  • Check your background job queue (BullMQ/Dragonfly). Federation delivery is asynchronous.
  • Verify that your SHARED_INBOX is accessible from the internet.
  • Check for signature verification errors in the logs.

"Signature verification failed"

  • Ensure your system time is accurate (NTP).
  • Check if your SSL certificate is valid.
  • Verify that your instance keys were generated correctly during setup.