Mastodon usernames different from the domain used for installation


When hosting on the steps are:

  1. choose a plan
  2. request the installation using the subdomain (
  3. follow the subscription and DNS settings steps
  4. create the redirect in the APEX/root domain (
  5. once you receive an email confirming the installation, reply to that email or email 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, a user on that server will be

This can be changed when you first install Mastodon. So, you can install Mastodon on but have your username be or even, 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 and have your usernames end in

First, you must have a valid TLS/SSL certificate on 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 The easiest is to make a redirect. Any query made to should redirect to and append to the URL any parameters passed.

How to create the redirect

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

location = /.well-known/webfinger {
  add_header Access-Control-Allow-Origin '*';
  return 301$request_uri;

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

RewriteEngine On
RewriteRule ^.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 even when parameters exist in the URL:

<?xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="">
  <Link rel="lrdd" type="application/xrd+xml" template="{uri}"/>

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

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.