Document how to use WEB_DOMAIN along with common pitfalls (#149)

* Create Serving_a_different_domain.md

Add extensive documentation for WEB_DOMAIN, as the feature is ill-documented and may be confusing.

* Fix Serving_a_different_domain.md

* Webfinger discovery workaround has made its way to v1.3.0

Running-Mastodon/Serving_a_different_domain.md

@@ -0,0 +1,85 @@
+Using a different domain name for Mastodon and the users it serves
+==================================================================
+
+Mastodon users are primarily identified by a `user@example.org` handle, and you might want
+this identifier to be the same as your email or jabber account, for instance.
+However, in this case, you are almost certainly serving some web content on https://example.org already,
+and you might want to use another domain (say `social.example.org`) for Mastodon itself.
+
+Luckily, there is support in Mastodon for that, but it might be tricky to set up, and any error
+might *prevent you from federating with other instances*.
+
+This guide attempts to explain the different mechanisms involved in such a setup, walk you through the configuration,
+and warn you about possible federation issues. It also assumes you have already read the [Production guide](Production-guide.md).
+
+## Account identifiers
+
+It is important to understand that for federation purposes, a user in Mastodon has two unique identifiers associated:
+- A webfinger `acct:` URI, used for discovery and as a verifiable global name for the user across Mastodon instances.
+  In our example, our account's `acct:` URI is `acct:user@example.org`
+- An author/actor URI, used in every other aspect of federation. This is the way in which users are identified in
+  OStatus, the underlying protocol used for federation with other Mastodon instances.
+  In our case, it is `https://social.example.org/users/user`.
+  It is not strictly required to be an URL, but they are in Mastodon's case to ease discovery of unknown remote accounts.
+
+Both account identifiers are unique and required for Mastodon.
+*An important risk if you set up your Mastodon instance incorrectly is to create two users (with different `acct:` URIs) with conflicting author/actor URIs*.
+
+## Webfinger
+
+As said earlier, each Mastodon user has an `acct:` URI, which is used for discovery and authentication.
+When you add `@user@example.org`, a webfinger query is performed. This is done in two steps:
+1. Querying `https://example.org/.well-known/host-meta` (where the domain of the URL matches the domain part of the `acct:` URI)
+   to get information on how to perform the query.
+   This file will indeed contain a URL template of the form `https://somedomain.org/.well-known/webfinger?resource={uri}` that
+   will be used in the second step.
+2. Fill the returned template with the `acct:` URI to be queried and perform the query:
+   `https://somedomain.org/.well-known/webfinger?resource=acct:user@example.org`
+
+## Configuring your Mastodon instance
+
+*DO NOT ATTEMPT TO CONFIGURE YOUR INSTANCE THIS WAY IF YOU DID NOT UNDERSTAND THE ABOVE*
+
+Also, make sure to check the known issues below.
+
+### Configuring Mastodon itself
+
+Mastodon has a two configuration variables in `.env.production` to enable using different domains for your users and Mastodon itself.
+Those two variables are `LOCAL_DOMAIN` and `WEB_DOMAIN`. When the latter is not set, it defaults to the value of
+`LOCAL_DOMAIN`.
+
+*Be extra careful when configuring your Mastodon instance, as changing `LOCAL_DOMAIN` without changing `WEB_DOMAIN`
+may cause remote instances to register different accounts with the same author/actor URI, which will result in federation issues!*
+
+- `LOCAL_DOMAIN` is the domain for which your Mastodon instance has authority, it is the domain used in the `acct:` URI.
+  In our example, `LOCAL_DOMAIN` would be set to `example.org`.
+- `WEB_DOMAIN` is the domain used for any URL generated for your instance, including the author/actor URIs.
+  In our case, that would be `social.example.org`.
+
+### Configuring domain.org
+
+Now, you have Mastodon running at `https://social.example.org` as well as a website at `https://example.org`.
+If you recall how webfinger queries work, the first step is to query `https://example.org/.well-known/host-meta`,
+which will contain an URL template.
+
+Therefore, the easiest way to configure domain.org is to redirect `/.well-known/host-meta` to social.example.org.
+
+With nginx, it would be as simple as adding:
+
+```nginx
+location /.well-known/host-meta {
+       return 301 https://social.example.org$request_uri;
+}
+```
+
+in example.org's server block.
+
+## Known issues
+
+There are a few known issues with Mastodon:
+
+- Current mastodon instances won't correctly process inbound salmon requests from instances where `WEB_DOMAIN`!= `LOCAL_DOMAIN`,
+  and will try resolving `acct:user@WEB_DOMAIN` instead of `acct:user@LOCAL_DOMAIN`.
+  Fortunately, since v1.3.0, Mastodon will reply to `acct:user@WEB_DOMAIN` queries with the account informations for `acct:user@LOCAL_DOMAIN`, effectively working around this issue at the cost of an extra webfinger discovery per interaction.
+- Mastodon does not actually use `WEB_DOMAIN` everywhere it should and will instead use whatever host it was accessed with.
+  For this reason, your Mastodon instance should only be reachable on `WEB_DOMAIN` and not `LOCAL_DOMAIN` (HTTP redirects are fine, but avoid proxying from `LOCAL_DOMAIN` to `WEB_DOMAIN`)