Synapse S3 storage provider service

• source code
• support

Synapse S3 storage provider is a module for the Synapse homeserver, which allows it to store its content repository files (audio/image/video/etc. chat attachments) in an object storage system like Amazon S3 or any other S3-compatible alternative (Wasabi, Backblaze B2, Cloudflare R2, etc).

Moving media files off of the server’s local filesystem and into an external storage (the S3 storage system) allows you to free up disk space on the Matrix server and effectively gives you infinite storage (for a relatively-cheap price).

To make your Matrix server use Synapse S3 storage provider, you first need to choose an Object Storage provider, then create the S3 bucket and finally send the details to us.

For new orders, you can provide the Synapse S3 Storage details right in our order form. For migrating existing servers to S3, contact us.

Choosing an Object Storage provider¶

You can create Amazon S3 or another S3-compatible object storage like Backblaze B2, Storj, Wasabi, Digital Ocean Spaces, etc.

Amazon S3, Backblaze B2, and Storj are pay-as-you with no minimum charges for storing too little data.

All these providers have different prices, with Storj appearing to be the cheapest (as of 2024-10, storage fee is $0.004 per GB/month, and egress fee is $0.007 per GB; check actual pricing here). Backblaze egress is free, but for only certain users for up to 3x the amount of data stored. Beyond that you will pay $0.01/GB of egress.

Wasabi has a minimum charge of 1TB if you’re storing less than 1TB, which becomes expensive if you need to store less data than that. Likewise, Digital Ocean Spaces has also a minimum charge of 250GB ($5/month as of 2022-10).

Here are some of the important aspects of choosing the right provider:

• if a provider is a company you like and trust (or dislike less than the others)
• if a provider implements end-to-end encryption of your data
• if a provider has a data region close to your Matrix server (if it’s farther away, high latency may cause slowdowns)
• if a provider’s infrastructure such as data center is centralized or distributed
• if a provider’s price model is transparent (whether it includes hidden costs like minimum charge, minimum storage term, etc.)
• if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) — likely not too important for the common use-case

Bucket creation and Security Configuration¶

Now that you’ve chosen an Object Storage provider, you need to create a storage bucket.

How you do this varies from provider to provider, with Amazon S3 being the most complicated due to its vast number of services and complicated security policies.

Below, we provider some guides for common providers. If you don’t see yours, look at the others for inspiration or read some guides online about how to create a bucket. Feel free to contribute to this documentation with an update!

Amazon S3¶

You’ll need an Amazon S3 bucket and some IAM user credentials (access key + secret key) with full write access to the bucket. Example IAM security policy:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "Stmt1400105486000",
			"Effect": "Allow",
			"Action": [
				"s3:*"
			],
			"Resource": [
				"arn:aws:s3:::your-bucket-name",
				"arn:aws:s3:::your-bucket-name/*"
			]
		}
	]
}

Note: This policy needs to be attached to an IAM user created from the Security Credentials menu. This is not a Bucket Policy.

Backblaze B2¶

To use Backblaze B2 you first need to sign up.

You can’t easily change which region (US, Europe) your Backblaze account stores files in, so make sure to carefully choose the region when signing up (hint: it’s a hard to see dropdown below the username/password fields in the signup form).

After logging in to Backblaze:

• create a new private bucket through its user interface (you can call it something like matrix-example-media-store)
• note the Endpoint for your bucket (something like s3.us-west-002.backblazeb2.com).
• adjust its Lifecycle Rules to: Keep only the last version of the file
• go to App Keys and use the Add a New Application Key to create a new one
  • restrict it to the previously created bucket (e.g. matrix-example-media-store)
  • give it Read & Write access

The keyID value is your Access Key and applicationKey is your Secret Key.

Other S3-compatible storage providers¶

For other S3-compatible providers, you most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner. You may not need to configure security policies, etc.

For details about setting up a bucket at Storj, please see the instruction here to get started.