95 lines
5.5 KiB
Markdown
95 lines
5.5 KiB
Markdown
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.
|
|
The host-meta file should 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 example.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.
|
|
|
|
Alternatively, you can serve the file from your hosting. The full content of the file:
|
|
```XML
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
|
|
<Link rel="lrdd" type="application/xrd+xml" template="https://social.example.org/.well-known/webfinger?resource={uri}"/>
|
|
</XRD>
|
|
```
|
|
|
|
## 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`)
|
|
- Remote Mastodon instances on v1.3.0, v1.3.1 or v1.3.2 from which you are following people won't PuSH new messages to your instance. This is a known bug, see [#2672](https://github.com/tootsuite/mastodon/issues/2672)
|