64 lines
2.8 KiB
ReStructuredText
64 lines
2.8 KiB
ReStructuredText
|
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.
|