Using Backblaze B2 (S3) Storage with Mastodon

Hero image showing the Mastodon and Backblaze logos against a plain background

This guide will show you how to add Mastodon content to a Backblaze B2 (S3) storage bucket, and in the process, reduce your server load!

The other day, I published a post on how to use Vultr Object storage (s3) to host your Mastodon attachment files, but of course, there are numerous different providers with S3-compatible API storage, and so today, I'm going to go through how you can get your Mastodon instance to play nicely with Backblaze's B2 storage.

Using Vultr Object (S3) Storage with Mastodon
This guide will show you how to use Vultr Object (S3) Storage with Mastodon to save local server resources.

Sign up to Backblaze

Of all the storage providers compatible with Mastodon, Backblaze is probably the most cost effective for those running a small instance, and they are quite upfront about their pricing. You'll pay $5 per TB/month for storage, and a small amount for egress ($0.01/GB). Stay tuned though, because we can cut the egress cost out altogether if we serve files via CloudFlare. That post will be coming soon. For the here and now: You can sign up and get 10GB free without having to enter any credit card information.

First step if you don't already have an account, is to sign up with Backblaze. On the signup form, make sure you choose the correct region (the option is not really obvious).

Create a Bucket

Once you've verified your email address and logged in, go to Buckets -> Create Bucket.

Name the bucket (something unique across the Backblaze systems - for the purposes of this demo, I called mine 'testbits'). For the other options, set:

  • Files in Bucket are: Public
  • Default Encryption: Disable
  • Object Lock: Disable (unless you specifically want this)
Screenshot showing Backblaze account before any buckets have been created
Showing Backblaze bucket creation window

On the left menu, go to 'Browse Files', click your bucket name and choose 'Upload'.

File upload icon within a 'browse files' pane within the Backblaze bucket

We're uploading a file here (doesn't matter what) to confirm the enpdoint URL. Once uploaded, click on the filename and you'll be shown various URLs. Make a note of the s3 URL - it will be in the format of yourbucketname.s3-endpoint-url

Showing a test image uploaded to a Backblaze bucket with metadata such as filename, friendly URL, S3 URL, native URL

Create an API Key

The last step in the Backblaze account is creating an app key. On the menu, choose 'App Keys' and scroll down to 'Add a New Application Key'.

Screenshot showing the link in the Backblaze panel for creating a new API key

Give it a name, and choose your bucket from the dropdown. For 'type of access' choose 'Read and Write', and leave the other 2 fields blank. Click 'Create New Key'.

Showing API key creation pane

You'll be presented with the ID and key. Make a note of these!

Example of the format API key credentials are provided in

Configure Mastodon

Now we're ready to tell Mastodon to use this new bucket!

If you're following the Mastodon installer, when it asks the question about S3 storage, say 'yes' and choose the Minio option.

Screenshot from command line showing the point in the mastodon installation process where you're prompted to configure an S3 bucket

Note 1: for the endpoint URL, use the s3 URL from earlier, but without your bucket name as a prefix. We enter the bucket name afterwards.

Note 2: for Minio access key, use the keyID, and for Minio Secret key, use the applicationKey.

Do you want to store uploaded files on the cloud? yes
Provider Minio
Minio endpoint URL:
Minio bucket name: testbits
Do you want to access the uploaded files from your own domain? no

We're saying 'no' to serving files from our own domain, but there will be a future post covering this, so check back soon!

If you already have a Mastodon instance running, as the mastodon user, edit the .env.production config file (which is usually in /home/mastodon/live) and edit/add the S3 lines:

Complete the rest of the setup, and when you're able to login, post an image, and if all goes well, it will upload to your new Backblaze B2 bucket!

It can take a few minutes for the file browsing on Backblaze to update and show the new files, but when you check, you'll see the Mastodon attachment file path.

That's it! You've added an S3-compatible Backblaze B2 bucket to your Mastodon instance, and have confirmed that new user-added files are being ingested.

Check back soon for a post on how we can serve these files from our own URL/subdomain, and cache the files to avoid serving more than required.

In the meantime, please leave a comment if you have any questions (or, more likely, I've made a mistake you want to point out). Alternatively, I'm over at @techbitsio.

Great! Next, complete checkout for full access to
Welcome back! You've successfully signed in
You've successfully subscribed to
Success! Your account is fully activated, you now have access to all content
Success! Your billing info has been updated
Your billing was not updated