Deploying Mastodon backed by a Backblaze CDN

Mastodon is quickly becoming a very popular social media app. The account @mastodonusercount put the total number of registered users at 15,499,978 back in October of 2024, with an average gain of +2,825 users per day.

I decided to deploy my own Mastodon instance, which I have now taken down due in most part to a lack of time. I will however share how I setup the instance, and how I was able to deploy a scalable, cost efficient CDN to store content.

What is Mastodon?

In short, Mastodon is part of the Fediverse, a distributed network of servers hosting compatible software. Mastodon servers, commonly referred to as instances, communicate to each other using the ActivityPub protocol.

Essentially, I post something to a Mastodon instance, and it publishes that post to every Mastodon instance that is subscribed to it, and vice versa.

Mastodon has become a go-to social networking space for a large number of people and for a variety of reasons. For some, it's about getting away from the large corporate social networking platforms like Facebook and away from targeted advertising.

For others, it's about being able to freely express yourself or have complete control over what your social media experience looks like.

Whatever your reason is for hosting a Mastodon instance, I'll dig into the how's and why's of utilizing a CDN in the first place, and then discuss why I specifically chose Backblaze.

Why use a CDN with Mastodon?

So because Mastodon operates on this pub/sub model, it means your instance is going to be caching a lot of images and videos. If your intent is to keep your Mastodon instance simply amongst a few people, then usually an old PC can easily store everything you're going to be browsing.

As your user base grows (and more specifically, the number of hashtags and other users they follow), the more storage space will be required.

As a quick example, my Mastodon instance - that had me as the only user - was storing 22 GB at the time I took Mastodon down, and keep in mind I had only been running this instance for a few months.

Scale this up with hundreds, or even thousands of active users, all searching for content across other Mastodon instances, as well as the likelihood that you'll be using a Relay to get your instance off the ground initially, and a DIY CDN becomes a simple way to store and deliver files.

Lastly, the way I setup this DIY setup was to also go via Cloudflare, meaning the content is cached, reducing the cost for egress from Backblaze.

Docker

Luckily for us, Backblaze operates using the S3 API, and Mastodon has built in S3 support.

First off, we will create a bucket in Backblaze B2. Make sure to note the Endpoint address, as we'll be using this later.

Next, we're going to obtain API credentials. This is done by going to your profile icon > My Settings > Application Keys.

I strongly recommend not using the master application key

Create a new application key, then copy it down.

Next, we're going to adjust our docker compose service to use S3, but pass in our endpoint.

mastodon:
    image: lscr.io/linuxserver/mastodon:latest
    container_name: mastodon
    environment:
      - PUID=1000
      - PGID=1000
      - S3_ENABLED=true
      - S3_BUCKET=[NAME OF B2 BUCKET]
      - AWS_ACCESS_KEY_ID=[APPLICATION KEY ID]
      - AWS_SECRET_ACCESS_KEY=[APPLICATION KEY SECRET ACCESS]
      - S3_ENDPOINT=https://[B2 ENDPOINT]
      - S3_ALIAS_HOST=[cdn.yourdomainhere.com]

Now that the docker compose side of things is done, we're going to want to configure cdn.yourdomainhere.com to point towards your B2 bucket.

DNS

B2 buckets will, by default, be inaccessible to all domains due to CORS configuration.

In Backblaze, hit CORS Rules next to your domain, tick the 'Share everything in this bucket with this one origin' option, and put 'https://*.yourdomainhere.com' then click 'Update CORS Rules'

Next, we're going to add the cdn.yourdomainhere.com to your DNS provider if you haven't done already. Things will get unique depending on your setup, but I pointed it at an NGINX reverse proxy using Nginx Proxy Manager.

In NGINX, you'll point your CDN domain to your B2 domain, but prefix the bucket name like so bucket-name.s3.region.backblazeb2.com

Next, you'll want to add the following custom Nginx configuration

  set $bucket "bucket-name.s3.region.backblazeb2.com";
  sendfile on;location / {
    resolver 8.8.8.8;
    proxy_http_version     1.1;
    proxy_redirect off;
    proxy_set_header       Connection "";
    proxy_set_header       Authorization '';
    proxy_set_header       Host $bucket;
    proxy_set_header       X-Real-IP $remote_addr;
    proxy_set_header       X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_hide_header      x-amz-id-2;
    proxy_hide_header      x-amz-request-id;
    proxy_hide_header      x-amz-meta-server-side-encryption;
    proxy_hide_header      x-amz-server-side-encryption;
    proxy_hide_header      Set-Cookie;
    proxy_ignore_headers   Set-Cookie;
    proxy_intercept_errors on;
    add_header             Cache-Control max-age=31536000;
    proxy_pass             https://$bucket;
  }

With this in place, you should now have a CDN domain which goes via Nginx to your B2 bucket. The S3_ALIAS_HOST environment variable in your Mastodon service should be that CDN domain, and you should be successfully both uploading to and downloading from that B2 bucket for images and video.