Creating a Domain Alias for Mastodon Files Served through DigitalOcean Spaces

As promised in my last missive, this post will take you through creating a custom domain alias for the files being served by a DigitalOcean Spaces bucket. What does that mean? Well, DigitalOcean Spaces is a cloud-based file storage that serves media like images, video, etc. This media can take-up a lot of storage, especially for an application like Mastodon, so it makes sense to offload it to a service is relatively inexpensive and prevents you from running into storage caps. Another benefit is that you can move your application more easily between hosting services without worrying about moving all the files, which often is the biggest time suck for migrations.

So that’s why one might use an S3-compatible storage service like Spaces for an application like Mastodon which I discussed in my last post, but why do you need a custom domain for serving those files? There are a few reasons:

  1. It makes moving between S3-cloud-based storage providers easier. For example, say I want to move between Spaces and my own, self-hosted Minio S-3 object storage server eventually, that would be possible without breaking links by keeping the domain consistent regardless of storage provider.
  2. When using a custom domain with Spaces you can actually access their content delivery network (CDN) which means the files are cached around their global network and files will be served faster.
  3. Finally, custom domains are awesome, how much better is a domain like  custom domain like versus …. no contest, right?

Ok, so now that you know the what and the why, let’s get into the how-to for DigitalOcean Spaces. The first piece is making sure you can point the domain you want to map on a Spaces bucket to DigitalOcean’s nameservers.  DNS can be confusing, but the piece here to keep in mind that for this to work is the entire domain needs to be pointed at DO’s nameservers, and this means you would control the DNS zones and pointing from their networking interface.This is not necessarily bad, it’s essentially the same thing you do with Cloudflare, but an issue could arise if you already have this domain managed elsewhere and changing the DNS records to a new service could mean overhead and downtime.

I just happened to have the domain I was thinking about running Mastodon on, but having already setup the server on, it was a simply redirecting traffic. So, I decided to point to DigitalOcean’s custom nameservers, which are,, and The nameservers are usually changed where ever you registered the domain. After that, you go to the Networking area of Digital ocean and add the domain, which will then allow you to manage and add new DNS records:

DNS management panel on DigitalOcean for

Once the domain is added, return to the Spaces bucket and enable the CDN option in settings:

Enable CDN option in Spaces bucket settings

Once the CDN option is enabled you will be asked to select a subdomain to load the files over, and now that you have pointed your domain’s nameservers to DigitalOcean you can do this. You can choose the domain and define the subdomain.

Creating subdomain and issuing certificate for Spaces CDN

I used, and this will automatically create a CNAME (or alias) that will make all the files served over also work over for the CDN, but most importantly served over Below are three examples of the same file resolving over all three domain names:

And that is the magic of alias domain mapping! Digital Ocean provides the Let’s Encrypt certificate that works for all the above domains, and now the ds106 Mastodon instance defaults to the domain for all media, which is quite slick. The subdomain, for this example, is a CNAME hostname, pointed to the value —this makes an alias of

CNAME for subdomain in DigitalOcean DNS panel

I learned this the hard way given I was initially confused about whether I could point a subdomain from another service like Cloudflare to the Spaces bucket (you can do this on AWS I’m pretty sure), and the short answer is you can’t. You have to point nameservers and then use DigitalOcean’s networking option to manage the domain, subdomain and SSL certificate.

Final step would be to add the environmental variable for the new alias to your .env.production file in Mastodon:

So my .env.production configuration for the object storage now looks like this, which is just the additional of the S3_ALIAS_HOST variable:


And that’s all folks! If everything is working as it should be your domain alias is working and you can test that by inspecting any image or avatar and checking the domain file URL.

NB: If I were a better guide writer I would re-do adding this subdomain to Spaces given I can’t remember the exact steps of how the subdomain was created (complicated by the fact I uploaded a certificate from Cloudflare while I was trying the old method) and how it creates the certificate, but I believe it is automatic and you can create a new subdomain such as files, but I really don’t want to delete this subdomain and do it again for the sake of this post given it will create a bit of havoc on the server 🙂

This entry was posted in Mastodon and tagged , , , , . Bookmark the permalink.

One Response to Creating a Domain Alias for Mastodon Files Served through DigitalOcean Spaces

  1. Pingback: The Allure of Mastodon | bavatuesdays

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.