takahe/docs/domains.rst

Domains

One of our key design features in Takahē is that we support multiple different domains for ActivityPub users to be under.

As a server administrator, you do this by specifying one or more Domains on your server that users can make Identities (posting accounts) under.

Domains can take two forms:

• Takahē lives on and serves the domain. In this case, you just set the domain to point to Takahē and ensure you have a matching domain record; ignore the "service domain" setting.
• Takahē handles accounts under the domain but does not live on it. For example, you wanted to service the @andrew@aeracode.org handle, but there is already a site on aeracode.org, and Takahē instead must live elsewhere (e.g. fedi.aeracode.org).

In this second case, you need to have a service domain - a place where Takahē and the Actor URIs for your users live, but which is different to your main domain you'd like the account handles to contain.

To set this up, you need to:

• Choose a service domain and point it at Takahē. You cannot change this domain later without breaking everything, so choose very wisely.
• On your primary domain, forward the URLs /.well-known/webfinger, /.well-known/nodeinfo and /.well-known/host-meta to Takahē.
• Set up a domain with these separate primary and service domains in its record.

Technical Details

At its core, ActivityPub is a system built around URIs; the @username@domain.tld format is actually based on Webfinger, a different standard, and merely used to discover the Actor URI for someone.

Making a system that allows any Webfinger handle to be accepted is relatively easy, but unfortunately this is only how users are discovered via mentions and search; when an incoming Follow comes in, or a Post is boosted onto your timeline, you have to discover the user's Webfinger handle from their Actor URI and this is where it gets tricky.

Mastodon, and from what we can tell most other implementations, do this by taking the preferredUsername field from the Actor object, the domain from the Actor URI, and webfinger that combination of username and domain. This means that the domain you serve the Actor URI on must uniquely map to a Webfinger handle domain - they don't need to match, but they do need to be translatable into one another.

Takahē handles all this internally, however, with a concept of Domains. Each domain has a primary (display) domain name, and an optional "service" domain; the primary domain is what we will use for the user's Webfinger handle, and the service domain is what their Actor URI is served on.

We look at HOST headers on incoming requests to match users to their domains, though for Actor URIs we ensure the domain is in the URI anyway.