Buckets

A bucket keeps an app's files outside its container: what its users upload, exports it writes, assets it generates. It speaks S3, so every S3 client and SDK works with it.

Keep files in a bucket rather than a volume when you can. A service with a volume runs on one server: it can't scale out across servers, and it can't move when its server goes. A service that keeps its files in a bucket stays free to sleep, scale out and move.

Make one

On the project's canvas, + Create → Bucket, and give it a name, like uploads. It sits on the canvas beside your services, with how much it holds, and a dashed line from each app that uses it. Click it to open its page.

Making a bucket makes a key for it, and shows the key's secret once. You only need it for a tool on your own computer: apps get it by reference (below).

Connecting an app

In the bucket's window, on Connect, choose the app and click Connect. The app gets five variables and is deployed with them:

Variable	Holds
S3_ENDPOINT	https://storage.smartalfred.com
S3_BUCKET	The bucket's name over S3, like uploads-k3m9x2ab
S3_REGION	auto
S3_ACCESS_KEY_ID	The key's id
S3_SECRET_ACCESS_KEY	The key's secret

What's stored on the app are references like ${{uploads.S3_BUCKET}}, not copies. Give the bucket a new key and the app has it with its next deploy.

Then use them in your code with any S3 SDK: buckets in your code.

Its files

The bucket's Files tab shows what's in it a folder at a time, with each file's size and when it changed; folders are how keys read up to each /. Open gives you the file through a link signed with the bucket's key and good for ten minutes; Delete removes it for good. The page's header says how much the bucket holds and roughly what that costs a month.

Good to know

• One upload in a single request can be up to 100 MB. Larger files go up in parts, which every S3 SDK does by itself for large files.
• Storage is billed like volumes, by the gigabyte-month of what's held. Requests and data transfer aren't billed.
• New key makes a new key and shows its secret once. The old key keeps working for a day, so connected apps carry on until their next deploy gives them the new one.
• Deleting a bucket deletes every file in it, for good. So does deleting its project.
• A project can have up to 10 buckets.
• A bucket's name can't be the name of a service in the same project: references name both the same way.
• Agents have the same: create_bucket, connect_bucket, list_buckets, rotate_bucket_key and delete_bucket in the agent tools.