If you want your mastodon handle to be shorter or different from the domain that you are hosted on, you'll need to make use of a WebFinger.

What Is A WebFinger?

WebFinger is an open protocol standard which Mastodon uses to identify users on other servers. Mastodon by default responds to requests for user information with the domain you are installed on, but it can be configured to tell them a different one.

The Problem This Solves

Often when companies and organizations go to setup Mastodon they already have a website located at their root domain, so they choose to install mastodon at a subdomain.

Subdomain: Fedihost uses the blogging software ghost to run this documentation. Because we have a website already occupying fedihost.co we setup our blog here at blog.fedihost.co

The issue is sometimes using a subdomain will make your mastodon handle long or hard to remember.

Easier Handles: A mastodon handle like @ceo@consultatron.com isn't just easier and tidier than @ceo@social.consultatron.com to remember. It can also match your email address.

By setting up a redirect on your webhosting and changing a configuration variable on your mastodon instance your users handles can be a shorter or different domain.

Before You Start

• It is not recommended that you do this on an instance that has already federated, as this will "Break Federation". The time to setup a WebFinger is when you are first setting up an instance.
• You will need access to your webhosting and have knowledge of how to configure a redirect on it
• You will need a host that allows you to change this setting such as FediHost

Steps

Let's have a look at how Consultatron would like @social.consultatron.com to be shortened to @consultatron.com. There aren't many steps to setting up WebFingers, but the timing and need for accuracy makes this somewhat unforgiving.

Change Mastodon Domain Variables

Ensure that in the initial setup of the instance before federation you have changed two .env variables.

Before Federation? Federation occurs when your instance interacts with other instances by following or responding to things on other instances. If your domain suddenly changes after connecting with a server any number of unexpected results can occur.

Mastodon has two environmental variables in .env.production which enable using different domains for your users and Mastodon itself.

// Filename: .env.production
LOCAL_DOMAIN=consultatron.com
WEB_DOMAIN=consultatron.com

Once these are set your mastodon instance is now telling people that it is located at consultatron.com even though in reality, it is being served from the subdomain at social.consultatron.com

On FediHost? Just type in your desired WebFinger during setup

Setup Redirect

Next setup a redirect on your web hosting for your existing domain.

When other mastodon instances go to look up the CEO profile of consultatron they will visit the URL:
https://consultatron.com/.well-known/webfinger?resource=acct:ceo@consultatron.com

But as we know, the REAL account and WebFinger are being served at the subdomain
https://social.consultatron.com/.well-known/webfinger?resource=acct:ceo@social.consultatron.com

So we need to make sure they see what they expecting, and not a page not found error using a 301 redirect.

This redirect will pipe the request that comes into your existing domain and return the expected result from the subdomain. You can do a 301 redirect in any major programming language which runs on a web server. However the most efficient and best way to do this is through a web server level configuration

Using Apache

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

Using NGINX

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

Check It Is Working

Once you have added these settings check everything is working by visiting your existing domain and requesting the webfinger of an account on your Mastodon instance

yourdomain.com/.well-known/webfinger?resource=acct:youraccount@yourdomain.com

Your should see the URL change in the address bar to the version with a subdomain and the browser will return a JSON object.