We’ve used S3 in production for about 2 years now, but it wasn’t until last night that I actually had to learn how it works.

I didn’t set it up initially, so I was just copying and pasting the initial implementation, rather than figuring out what was going on. This led to a few really irritating issues with filenames and permissions.

After spending the time to actually read about how it works, I realized that it’s ridiculously simple and I should have learned it earlier.

This post will review what you can do, rather than how to do it.

Buckets

A bucket is a container for your files. You can set default permissions for buckets. You can have files in buckets show up in three ways:

bucket_name.s3.amazonaws.com/filename

s3.amazonaws.com/bucket_name/filename

bucket_name.your_domain.dom/filename

The last way requires setting up your nameserver to point to s3.

Objects

Objects are files with permissions and metadata. They can have arbitrary metadata that is basically a hash. Objects are stored in buckets. You can’t update the actual file data, you have to over write it. You can update the metadata and permissions.

ACL

S3 handles permissions by having an access control list. There are only a few options. I’ll review the most common.

First, you can simply allow everyone to see the file. Second, you can allow only authenticated users to see it. If you do it this way, then you basically create a signature that you then add to the url and that matches with s3. You can set a time limit on how long the signature will be valid for. Finally, you can set it so that only you can access the file.

Implementation

While it’s really old, the AWS::S3 gem is very well documented and very useful. Its documentation can be understood in a few minutes, and the code is really easy to understand. You can find the docs here. I recommend starting by reading the entire homepage.

Gui

There’s a Java app called Jets3t that lets you easily browse, update, and delete all of your buckets and files in a simple gui. Download jets3t here.