Choosing a Mattermost File Storage Backend: Local Disk vs. Amazon S3

Mattermost writes every uploaded attachment, profile picture, and export to a single storage driver. The choice between the default local filesystem and Amazon S3 is not just a preference; it determines whether your deployment can grow past one server, how you back up data, and what happens when a node fails. The practical takeaway: start with local disk for small, single-server installations, but switch to S3 before you add a second Mattermost node or need durability that survives hardware loss.

The decision and its constraints

You are choosing where Mattermost keeps binary file data. The constraints that usually drive the decision are:

• Durability: whether the storage survives a disk failure, server loss, or accidental deletion.
• Cost: both the direct storage price and the operational effort to maintain it.
• Scale: whether you plan to run multiple Mattermost application servers behind a load balancer.
• Compliance: organizational policies that require encrypted, off-site, or auditable object storage.

Local disk vs. Amazon S3: a side-by-side comparison

Option	Setup complexity	Cost model	Durability	Typical use case
Local disk	Low (default)	Low: storage on server	Depends on server RAID/backup	Small teams, dev/test
Amazon S3	Moderate (IAM, bucket)	Pay-as-you-go storage + requests	High (designed for 11 nines durability)	Large scale, multi-node HA

Trade-offs in practice

When local disk is the right answer

Local storage requires no external accounts, no IAM policies, and no network round-trips for uploads. Backup is whatever procedure you already use for the Mattermost server. The trade-off is that files live on one node. If that server fails and you have no off-site backup, the files are gone. Horizontal scaling also becomes difficult because a second Mattermost node cannot see files written by the first unless you share the volume at the operating-system level, which adds its own complexity.

When S3 is the right answer

Amazon S3 turns Mattermost application servers into stateless workers. Any node can serve any file because the bytes live in a central bucket. You gain durability designed for eleven nines, automatic scaling, and the ability to attach bucket lifecycle rules for cost control. The cost is operational: you must manage IAM credentials, bucket policies, and request pricing. For busy servers, S3 request charges can rival storage charges, so monitor the bill.

Implementation: switching to Amazon S3

Before changing anything, confirm that your Mattermost release supports the S3 driver. Mattermost has supported Amazon S3 for many releases, but configuration keys evolve. Check the documentation for your specific version.

1. Create the bucket and IAM policy

In AWS, create a dedicated S3 bucket. Then attach an IAM policy—Identity and Access Management rules that define which API actions a user or role may perform—to the Mattermost server's role or user. Grant at least:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject

Scope the policy to the bucket ARN, for example arn:aws:s3:::mattermost-files/*. If your deployment lists objects or uses server-side encryption with a custom key, additional permissions may be required.

2. Edit Mattermost configuration

On the Mattermost server, open config.json—commonly located under /opt/mattermost/config/—and set the FileSettings.DriverName to amazons3. A typical block resembles the following; treat the keys as a starting point and verify them against your version's schema:

{
  "FileSettings": {
    "DriverName": "amazons3",
    "AmazonS3AccessKeyId": "<key>",
    "AmazonS3SecretAccessKey": "<secret>",
    "AmazonS3Bucket": "mattermost-files",
    "AmazonS3Region": "us-east-1",
    "AmazonS3SSL": true,
    "AmazonS3V2Auth": true
  }
}

If you are staying on local disk, leave DriverName as an empty string "", which is the default.

3. Restart and validate

Restart the Mattermost service. On a systemd host, that is typically sudo systemctl restart mattermost. If your distribution includes the validation tool, run mattermost config validate on the server before restarting to catch schema errors. After the service returns, upload a small file through the web interface. Then run the following from any terminal with AWS credentials configured:

aws s3 ls s3://mattermost-files/ --recursive

Expected check: the uploaded object should appear in the listing. Download the file again in Mattermost to confirm read access. Finally, inspect the Mattermost server logs for lines containing StorageDriver; there should be no errors during the upload and download cycle.

Limitations and migration risk

Changing the storage driver after files already exist does not move the old data. If you switch from local disk to S3 without migrating, existing links break because Mattermost looks for the old files in the new backend. Plan a migration window: either copy the data directory contents to the bucket using a tool that preserves object keys, or keep the old files accessible until links age out.

S3 is not free. Request pricing, data transfer, and storage class choices affect the bill. Local disk is not durable by itself; RAID protects against a single drive failure, not against server loss or ransomware. Neither option removes the need for a tested backup strategy.

A practical checklist

1. Confirm your Mattermost version supports the S3 driver and note the exact config keys.
2. Create the bucket and least-privilege IAM policy.
3. Back up config.json and the local data directory before editing.
4. Update FileSettings and restart the service.
5. Upload, download, and delete a test file; verify the object lifecycle in S3.
6. Check logs for StorageDriver errors.

If you need to roll back to local disk after a pilot, set DriverName back to "" and restart. Only do this after confirming that no new files were written to S3, or after migrating those files back to the local data directory; otherwise recent attachments will be missing.