HOWTO access Amazon S3 with Ruby

Amazon S3 is commonly used in web applications for file storage. This guide will show you how to access the Amazon S3 API with Ruby and version 3 of the official AWS SDK for Ruby.

Finding your credentials

First you’ll need to get your access key credentials from the AWS Management Console.

IAM access keys are best for production applications, and can be managed from the "Security Credentials" tab of the IAM user page. Alternatively you can use a root access key, which you can find in the "Access Keys" section of the account-wide "Security Credentials" page—root keys are more of a security risk because they grant access to everything in your AWS account, but easier to use if you’re new to AWS.

You’ll also need to pick a region (see the AWS General Reference for a list).

Setting up your credentials

For a production app it’s best to store your credentials in environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION). The AWS SDK will pick up the credentials from the environment variables automatically.

Alternatives for development and quick scripting are to store your credentials in an ini formatted config file (~/.aws/credentials), or paste them directly into your code.

Installing the aws-sdk gem

Make sure you have the aws-sdk-s3 gem installed:

gem install aws-sdk-s3

Alternatively add the gem to your Gemfile and install it via bundler.

Listing buckets

Copy/paste the following short Ruby script:

require 'aws-sdk-s3'

s3 = Aws::S3::Client.new

response = s3.list_buckets

response.buckets.each do |bucket|
  puts "#{bucket.creation_date} #{bucket.name}"
end

Run the script with a ruby and you should see a list of your S3 buckets. Of course if this is the first time you’ve used S3 there might not be any buckets to display, but if you don’t see any exceptions you know you’ve configured everything correctly.

Creating a bucket

You can create buckets programmatically by calling #create_bucket, like this:

s3.create_bucket({
  bucket: 'BucketName',
  acl: 'private',
  create_bucket_configuration: {
    location_constraint: 'eu-west-1'
  }
})

Although not required you typically want to specify the location constraint (the region the bucket is hosted in) and the ACL (which determines who has access to the bucket).

Uploading a file

You can upload files to S3 using the #put_object method, like this:

File.open('/path/to/local/filename.html', 'rb') do |file|
  s3.put_object({
    bucket: 'BucketName',
    key: 'filename.html',
    body: file
  })
end

The body can also be a string when uploading data from memory. The gem also includes support for multipart uploads, which makes it possible to upload larger files in chunks.

Check the documentation for a full list of Aws::S3::Client methods you can call.