Improve domains docs

docs/domains.rst

@@ -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