diff --git a/Running-Mastodon/Serving_a_different_domain.md b/Running-Mastodon/Serving_a_different_domain.md new file mode 100644 index 00000000..46a47047 --- /dev/null +++ b/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`)