Write some more docs

1 files changed, 63 insertions, 0 deletions

diff --git a/docs/domains.rst b/docs/domains.rst
new file mode 100644
index 0000000..8819e30
--- /dev/null
+++ b/docs/domains.rst
@@ -0,0 +1,63 @@
+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.