Mastodon instances store user uploads such as images, videos, and files. Every instance operator must choose between storing these files on the local disk of the server or using an object storage service like Amazon S3 or a compatible alternative. The choice affects performance, cost, scalability, and data durability. This article compares the two approaches and explains the tradeoffs for instance administrators.
Key Takeaways: S3 Object Storage vs Local Disk for Mastodon Media
- Environment variable S3_ENABLED: Set to true to activate S3-compatible storage for user uploads.
- Environment variable PAPERCLIP_ROOT_PATH: Defines the local disk path used when S3 storage is disabled.
- Environment variable S3_BUCKET: Specifies the S3 bucket name where Mastodon stores media files.
Understanding Mastodon Media Storage Options
Mastodon uses the Paperclip gem to handle file attachments. By default, Paperclip saves uploaded files to the server’s local filesystem. The storage path is set by the environment variable PAPERCLIP_ROOT_PATH. This approach is simple and requires no additional services.
When you enable S3-compatible object storage, Mastodon redirects Paperclip to upload files to a remote bucket. The instance then serves files directly from the object storage URL. This setup requires setting S3_ENABLED=true and providing bucket credentials. Supported providers include Amazon S3, DigitalOcean Spaces, Wasabi, Backblaze B2, and any service that offers an S3-compatible API.
What Gets Stored
Both storage methods handle the same types of files: profile avatars, header images, media attachments in toots, custom emoji, and preview cards. The instance database stores only file paths or URLs. The actual binary data resides either on local disk or in the object storage bucket.
When the Choice Matters
The decision has the biggest impact when your instance grows beyond a single server. A small personal instance with fewer than 100 active users may run comfortably on local disk. A medium or large instance with thousands of users will quickly fill a local disk and strain the server’s I/O capacity. Object storage becomes necessary for horizontal scaling.
Comparing S3 Object Storage and Local Disk for Mastodon
Each storage method has clear advantages and drawbacks. The following sections break down the key tradeoffs.
Performance and Latency
Local disk offers the lowest latency for file reads and writes. The web server reads directly from the same machine. Object storage adds network round-trips. Each media request must travel from the instance to the object storage provider and back. This adds 10 to 50 milliseconds per request under normal conditions. Caching with a CDN can reduce the impact for frequently accessed files.
For write operations, object storage is slower because each upload requires a full HTTP PUT request. Local disk writes are nearly instant. The difference matters most during bulk operations such as importing custom emoji or processing video uploads.
Scalability
Local disk does not scale horizontally. If you add more application servers behind a load balancer, each server must have its own copy of the media files. You would need a shared filesystem such as NFS or GlusterFS, which adds complexity and can become a bottleneck. Object storage is inherently shared. Every application server can read and write to the same bucket without additional configuration.
Cost
Local disk cost is predictable. You pay once for the storage capacity of your server. The cost is typically lower per gigabyte than object storage. However, you must also account for backups. A full server backup that includes media files can be large and expensive to store.
Object storage charges are usage-based. You pay for storage used, data transferred out, and API requests. Costs can grow quickly if your instance serves many large files. Some providers offer free egress within their ecosystem. For example, files stored in DigitalOcean Spaces served to a DigitalOcean Droplet incur no transfer fees.
Data Durability and Redundancy
Local disk provides no redundancy by default. If the disk fails, all media files are lost unless you maintain separate backups. Object storage providers replicate data across multiple availability zones. Amazon S3 Standard offers 99.999999999% durability. This level of protection requires no extra effort from the instance operator.
Maintenance Overhead
Local disk requires manual maintenance. You must monitor disk usage, rotate logs, and prune old media files. The Mastodon admin CLI provides commands such as tootctl media remove to delete unused attachments. You must also manage disk backups yourself.
Object storage reduces the maintenance burden. The provider handles hardware failures and disk replacements. You still need to manage lifecycle policies to delete old files and control costs. Most S3-compatible services allow you to set automatic expiration rules on the bucket.
Security Considerations
Local disk files are accessible only through the web server. There is no external attack surface for the storage layer. Object storage requires secure credential management. If your S3 access keys leak, an attacker can read or delete all media files. You should use IAM roles or environment variables with restricted permissions. Never hardcode keys in the source code.
Common Configuration Mistakes and Limitations
Misconfigured S3 Endpoint Causes Upload Failures
If you set S3_ENABLED=true but provide an incorrect endpoint URL, Mastodon will fail to upload any media. The error appears in the logs as a Net::OpenTimeout or Net::ReadTimeout. Double-check the endpoint value. For Amazon S3, use https://s3.REGION.amazonaws.com. For DigitalOcean Spaces, use https://REGION.digitaloceanspaces.com.
Bucket Permissions Block Public Access
Mastodon serves media files directly from the object storage URL. The bucket must allow public read access. If the bucket blocks public access, users will see broken images. Set a bucket policy that grants s3:GetObject to Principal: "". Restrict write access to only the Mastodon application.
CORS Headers Missing for Direct Uploads
When Mastodon uses direct upload to S3, the browser sends a cross-origin request. If the bucket does not return the correct CORS headers, the upload fails silently. Configure the bucket CORS policy to allow the origin of your Mastodon instance and the methods PUT, POST, and GET.
Local Disk Storage Cannot Be Migrated Without Downtime
If you start with local disk and later switch to S3, existing media files remain on the local server. Mastodon will serve new uploads from S3 but old files still come from the local path. To migrate, you must copy all existing files to the S3 bucket and update the database records. The migration process requires the instance to be in maintenance mode to prevent data inconsistency.
| Item | Local Disk | S3 Object Storage |
|---|---|---|
| Read latency | Very low (local filesystem) | Moderate (network round-trip) |
| Write latency | Very low | Moderate to high |
| Horizontal scaling | Requires shared filesystem | Built-in shared access |
| Storage cost | Fixed per server | Usage-based (grows with traffic) |
| Data durability | Dependent on backups | Provider-managed replication |
| Maintenance effort | High (monitor disk, prune files) | Low (provider handles hardware) |
| Security risk | Low (no external storage layer) | Moderate (credential management) |
| Migration complexity | N/A | Low to medium (copy existing files) |
You now have a clear picture of the tradeoffs between local disk and S3 object storage for your Mastodon instance. Start with local disk if you run a small single-server instance and want the simplest setup. Switch to S3-compatible storage when you need to scale beyond one server or when you want automated redundancy. Use the tootctl media remove command regularly regardless of your storage choice to keep disk usage under control.