Improve domains docs

This commit is contained in:
Andrew Godwin 2022-12-26 20:27:23 -07:00
parent b36fa0de51
commit 201b410383

View file

@ -7,22 +7,53 @@ 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:
We have two terms for domains:
* **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.
* **Display Domains** are the domains that appear in handles (for example,
``jointakahe.org`` in ``@takahe@jointakahe.org``)
* **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``).
* **Service Domains** are the domains that actually route to Takahē and let
you access all its pages and APIs.
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.
There's then two ways of running domains given those definitions:
Service domains **must be unqiue** - they are how we identify what domain the
* A domain acting as **both display and service domain**. This is for when
you're OK giving over a whole domain to Takahē (e.g. ``takahe.social``).
* A separate **display domain** from the **service domain**, for when you still
want to run a website on the display domain (e.g. ``jointakahe.org``) but
also want to use it for handles.
Let's look at how to set each type up.
Combined Domain
---------------
In this case, you want to set up a domain that only runs Takahē and doesn't
have any other website to host - an example of this is our own
`takahe.social <https://takahe.social>`_.
To do this, you should set the domain up in Takahē as follows:
* **Domain**: Set this to the domain you're using
* **Service Domain**: Leave this blank (as the one domain is doing both jobs)
Split Domain
------------
In this case, you want to allow users to have handles that include a domain
that is already serving another website - for example, our own
`jointakahe.org <https://jointakahe.org>`_ serves our main webpage, but we also
have our main account as ``@takahe@jointakahe.org``.
To make this work, 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.
Service domains **must be unique** - they are how we identify what domain the
request that is coming in is for. It doesn't matter what it is, as long as it's
unique and it serves Takahē. For example, ``jointakahe.org`` has a service
domain of ``jointakahe.takahe.social``, but we could also have chosen
@ -30,14 +61,61 @@ domain of ``jointakahe.takahe.social``, but we could also have chosen
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.
* Choose a service domain specifically for this display 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ē.
* On your display domain, proxy the URLs ``/.well-known/webfinger``,
``/.well-known/nodeinfo`` and ``/.well-known/host-meta`` to your service
domain (or anything that's serving the same Takahē install).
* Set up a domain with these separate primary and service domains in its
record.
.. note::
You can also do a HTTP redirect rather than proxying if you like, though it
may be slightly less compatible with all Fediverse server software.
* Set up a domain with:
* **Domain**: Set this to the display domain
(the one that doesn't point at Takahē)
* **Service Domain**: Set this to the service domain (the one that serves
Takahē)
Example
-------
Let's say that we want to serve three domains from the same Takahē installation:
* ``takahe.social``, which will just serve Takahē directly
* ``jointakahe.org``, which has an existing website that needs to keep working
* ``aeracode.org``, which also has a website that needs to work
We set them up in the following way:
* ``takahe.social``
* Domain: ``takahe.social``
* Service Domain: *(left blank)*
* ``jointakahe.org``
* Domain: ``jointakahe.org``
* Service Domain: ``jointakahe.takahe.social``
* ``aeracode.org``
* Domain: ``aeracode.org``
* Service Domain: ``fedi.aeracode.org``
Then, we need to make sure Takahē is accessible via ``takahe.social``,
``jointakahe.takahe.social`` and ``fedi.aeracode.org``, as these are our
service domains.
Finally, we need to ensure the ``.well-known`` paths are proxied from
``jointakahe.org`` and ``aeracode.org`` to Takahē, as these are the display
domains that have separate service domains.
Technical Details