How to Configure Mastodon Instance With Wasabi S3-Compatible Storage

Mastodon instances store user media files such as images, videos, and profile avatars. By default, these files are saved on the instance server’s local disk. As your instance grows, local storage fills up quickly and becomes expensive to expand. Wasabi offers a cost-effective S3-compatible object storage solution that integrates directly with Mastodon. This article explains how to configure your Mastodon instance to use Wasabi as its media storage backend.

Understanding Wasabi S3-Compatible Storage for Mastodon

Wasabi is a hot cloud storage service that is fully compatible with the Amazon S3 API. This means Mastodon can use Wasabi as a drop-in replacement for AWS S3. The main benefit is cost: Wasabi charges no egress fees and has a flat storage price lower than AWS S3 for many regions. Mastodon uses the fog-aws gem to communicate with S3-compatible services. When S3 storage is enabled, Mastodon uploads all user media files to the configured bucket instead of saving them on the local filesystem. This offloads storage overhead from the instance server and makes scaling easier.

Before starting the configuration, you need a Wasabi account with an active subscription. You also need SSH access to your Mastodon server and the ability to edit its environment file. The default location for this file is /home/mastodon/live/.env.production or inside a Docker compose configuration. If you use Docker, the environment variables are typically set in a .env file or directly in the docker-compose.yml file.

Steps to Configure Mastodon to Use Wasabi S3 Storage

Follow these steps in order to connect your Mastodon instance to Wasabi. The process involves creating a Wasabi bucket, generating credentials, and editing the Mastodon environment file.

1. Create a Wasabi bucket
   Log in to your Wasabi console. Navigate to the Buckets section and click Create Bucket. Choose a globally unique bucket name, for example mastodon-media-yourinstance. Select the region closest to your server, such as us-east-1 or eu-central-1. Leave the default settings for object locking and versioning unless you have specific requirements.
2. Generate access keys in Wasabi
   In the Wasabi console, go to Access Keys. Click Create New Access Key. Copy the Access Key ID and Secret Access Key. Store these securely. You will not be able to see the Secret Access Key again after closing the dialog.
3. Find the Wasabi S3 endpoint for your region
   Wasabi provides different endpoints per region. For example, the endpoint for us-east-1 is s3.us-east-1.wasabisys.com. Refer to the Wasabi documentation for the exact endpoint URL of your chosen region.
4. Edit the Mastodon environment file
   SSH into your Mastodon server. If you installed Mastodon from source, open the environment file with nano /home/mastodon/live/.env.production. If you use Docker, edit the .env file in the Mastodon directory. Add or modify the following lines:

   S3_ENABLED=true
S3_BUCKET=mastodon-media-yourinstance
AWS_ACCESS_KEY_ID=your-wasabi-access-key
AWS_SECRET_ACCESS_KEY=your-wasabi-secret-key
S3_ENDPOINT=https://s3.us-east-1.wasabisys.com
S3_REGION=us-east-1
S3_PROTOCOL=https
S3_HOSTNAME=s3.us-east-1.wasabisys.com

   Replace the bucket name, keys, endpoint, and region with your actual values. The S3_HOSTNAME should match the hostname part of the endpoint URL without the protocol.

5. Save the file and apply changes
   Save the environment file and exit the editor. If you use Mastodon from source, run RAILS_ENV=production bin/tootctl assets:precompile to regenerate the asset pipeline. This step is optional but recommended to ensure any new asset paths are correct.
6. Restart Mastodon services
   Restart the Mastodon web and Sidekiq processes to load the new environment variables. For a source installation, use systemctl restart mastodon-web mastodon-sidekiq. For Docker, run docker compose restart web sidekiq.
7. Verify the configuration
   Upload a test image to Mastodon, for example a profile avatar. After uploading, check the Wasabi bucket. The file should appear in the bucket under a path like media_attachments/files/000/.... If the file appears, the configuration is working correctly.

Common Issues and Misconfigurations

Files still save to local disk after configuration

This usually happens when the environment variables are not read by Mastodon. Verify that the .env.production file is owned by the mastodon user and has the correct permissions. Run chown mastodon:mastodon /home/mastodon/live/.env.production and chmod 600 /home/mastodon/live/.env.production. Then restart the services again.

403 Forbidden errors when uploading

A 403 error indicates that the access keys do not have permission to write to the bucket. Go to the Wasabi console and check the bucket policy. Ensure the access key belongs to a user or root account that has write permissions. Also verify that the bucket name is correct and that the endpoint URL matches the region exactly.

Existing media files not migrated to Wasabi

Configuring Wasabi does not automatically move existing files. To migrate existing media, use the Mastodon CLI tool. Run RAILS_ENV=production bin/tootctl media:remove to remove local copies after they are uploaded to S3. However, this command only removes cached thumbnails and remote media. For a full migration of all local files, you need to copy them manually or use a script to upload them to the Wasabi bucket while preserving the path structure.

Uploaded files are not publicly accessible

By default, Wasabi buckets are private. Mastodon signs URLs for access, so public bucket policy is not required. If you see broken images after upload, check that the S3_ENDPOINT and S3_HOSTNAME are correctly set. Also confirm that the region matches the bucket region. A mismatch causes Mastodon to generate incorrect signed URLs.

Item	Wasabi	AWS S3
API Compatibility	Fully S3-compatible	Native S3 API
Egress Fees	No egress fees up to 1x stored data per month	Egress fees apply per GB
Storage Cost (us-east-1)	$5.99 per TB per month	$23 per TB per month (S3 Standard)
Minimum Storage Duration	90 days per object	No minimum
Mastodon Configuration	Requires S3_ENDPOINT and S3_HOSTNAME	Works with default fog-aws settings

You have now configured your Mastodon instance to store all media files on Wasabi S3-compatible storage. This reduces local disk usage and lowers storage costs for growing instances. Next, consider setting up a lifecycle policy in Wasabi to automatically delete old cached media after a set number of days. Use the Mastodon CLI command RAILS_ENV=production bin/tootctl media:remove --days=7 to remove remote media cached locally older than 7 days, keeping your bucket lean.