how to setup mastodon forwarding from your custom domain using webfinger and github pages
by @me@juno.lol
tldr
say you have your own domain, cool.example, and you'd rather use very@cool.example as your identity instead of cool23234543@mastodon.social. you can!
prerequisites
I'll assume you already have a repo setup with github pages turned on (or some other static site hosting), and that you already have a mastodon account somewhere.
theory
mastodon, the hot new social network thing, is built on a series of open protocols. One is webfinger, a way to look up accounts like "foo@bar.com" and figure out how to do stuff with them (like follow them on mastodon).
the "web" part of webfinger is that it returns plain json via a URL, eg https://cool.example/.well-known/webfinger?resource=very@cool.example
if we're ok using the same forwarding information for any account on the domain, we can ignore the resource query param and use a static json document as our response!
howto
step 0 - enable publishing .well-known (only in github pages)
look for a file called _config.yaml - edit it or add it if it doesn't exist. add this to the file:
include: [".well-known"]this let's github pages publish the files we'll add next - otherwise, they'll be ignored
step 1 - configure webfinger
add a file called /.well-known/host-meta containing:
<xml version="1.0" encoding="UTF-8"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
<Link rel="lrdd" template="https://cool.example/.well-known/webfinger?resource={uri}" type="application/xrd+xml" />
</XRD>(replace cool.example with your domain) (this is oldschool xml - case matters! just leave it as-is)
the internet is based on 18 layers of pedantry, and this file will help increase compatibility.
step 2 - download your existing mastodon account info
in a browser tab, go to https://mastodon.social/.well-known/webfinger?resource=acct:YOURNAME@mastodon.social (replace mastodon.social in both places with your instance domain, if needed)
you should see a bunch of json. copy and paste this, as-is, into a new file in your repo, called /.well-known/webfinger.
step 3 - publish and test
make sure all 3 files in steps 0-2 are committed to your github pages repo. in a browser, check that you're able to access https://cool.example/.well-known/webfinger and that it returns your account json.
finally, go to mastodon and try searching for anything@cool.example - you should see your profile come up- voila!
if you want to see an example, check out my super basic gh pages site, https://github.com/junosuarez/juno.lol
gotchas + caveats
this is like the basic email forwarding that some domain registrars offer - people can contact you at this address, but your outgoing mail will come from your actual email provider.
similarly, this method will let people search for your by your custom domain address, but your posts will appear to come from your home mastodon instance address.
if you really want the full custom domain experience, you'll have to get fancier, maybe even run your own mastodon instance - but that's outside the scope of this gist.
thanks
this gist is based heavily on this blog and this gh issue. i first got the inkling to want to do this based on this post