Mastodon usernames different from the domain used for installation

TL;DR

When hosting on Masto.host the steps are:

  1. choose a plan
  2. request the installation using the subdomain (social.example.com)
  3. follow the subscription and DNS settings steps
  4. create the redirect in the APEX/root domain (example.com)
  5. once you receive an email confirming the installation, reply to that email or email info@masto.host requesting the configuration change to use your domain for usernames
  6. do not follow remote accounts until you receive the email reply confirming the configuration change

By default, when you install Mastodon on a domain or subdomain, that will determine how the username of users on that Mastodon server will be. For example, if you install Mastodon on social.example.com, a user on that server will be @myusername@social.example.com.

This can be changed when you first install Mastodon. So, you can install Mastodon on social.example.com but have your username be @myusername@example.com or even @myusername@differentdomain.com, but that requires a configuration change to the domain used for usernames.

Notice: you can only make this change if your server has not previously federated with remote servers or this can/will break remote federation.

For this example, let’s assume you want to install Mastodon on social.example.com and have your usernames end in example.com.

First, you must have a valid TLS/SSL certificate on example.com. Meaning that the domain should be accessible via HTTPS.

Second, you need to create a response URL template response to when a webfinger query is made on https://example.com/.well-known/webfinger. The easiest is to make a redirect. Any query made to https://example.com/.well-known/webfinger should redirect to https://social.example.com/.well-known/webfinger and append to the URL any parameters passed.

How to create the redirect

Now, if on example.com you are using NGINX you can do something like:

location = /.well-known/webfinger {
  add_header Access-Control-Allow-Origin '*';
  return 301 https://social.example.com$request_uri;
}

If on example.com you are using Apache, you can do something like:

RewriteEngine On
RewriteRule ^.well-known/webfinger(.*)$ https://social.example.com/.well-known/webfinger$1 [L,R=301]

I have received reports of people using a static XML file that have also worked, but I am unsure what problems this might cause. Something like this should respond on https://example.com/.well-known/host-meta even when parameters exist in the URL:

<?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.com/.well-known/webfinger?resource={uri}"/>
</XRD>

Finally, in the Mastodon configuration (.env.production) you should set LOCAL_DOMAIN and WEB_DOMAIN values. Using the previous example:

LOCAL_DOMAIN=example.com
WEB_DOMAIN=social.example.com

If you are hosting with me, this final step about the Mastodon configuration is unnecessary. You just need to email requesting that change after the installation process has finished.