s3lurp - Browser Uploads Direct to S3

direct s3 upload Rails form helper

Installation

Add this line to your application's Gemfile:

gem 's3lurp'

And then execute:

$ bundle

Or install it yourself as:

$ gem install s3lurp

Configuration

S3lurp has many options that can be configured globally or passed to the helper via a hash.

AWS S3 Setup

There are three options required for buckets that are not public-write:

  • s3_bucket - The name of the bucket where files go
  • aws_access_key - This is your AWS Access Key ID
  • aws_secret_key - Your AWS Secret Accss Key

These three options can be set via a yaml config file, an initializer, or ENV vars.

ENV['S3_BUCKET']
ENV['AWS_ACCESS_KEY']
ENV['AWS_SECRET_KEY']

Another way to set up these options is to us an initializer.

In config/initializers/s3lurp.rb

S3lurp.configure do |config|
  config.s3_bucket = "bucket_of_holding"
  config.aws_access_key = "some_acces_key"
  config.aws_secret_key = "keep_it_secret"

Finally you can use use a yaml file to load the configuration.

# config/initializers/s3lurp.rb
S3lurp.congigure do |config|
  config.file = 's3lurp.yml'
end
# config/s3lurp.yml
development:
  s3_bucket: "dev_bucket"
  aws_access_key: "dev_key"
  aws_secret_key: "dev_secret"
production:
  s3_bucket: "prod_bucket"
  aws_access_key: "prod_key"
  aws_secret_key: "prod_secret"

Using a yaml conifg file allows you to use different settings for different environments. Note: It's not necessary to provide environment based settings. The yaml can just be a set of key/value pairs without any grouping by environment.

S3lurp Config Example

Here is an exmaple of how to configure s3lurp using Heroku.

Setup your ENV variables for heroku and for local use. For more on Heroku config see here: https://devcenter.heroku.com/articles/config-vars

$ heroku config:add AWS_ACCESS_KEY=asdfg12345 AWS_SECRET=qwertyu0987622`
$ export AWS_ACCESS_KEY=asdfg12345
$ export AWS_SECRET=qwertyu0987622

Set up some defaults with an initialzer

# config/initializers/s3lurp.rb
S3lurp.congigure do |config|
  config.acl = 'public-read'
  config.minutes_valid = '600'
  config.max_file_size = 10.megabytes
  config.min_file_size = 1024
end

And now in your view you can call

s3_direct_form_tag({:key => 'photos/uuid/${filename}'})

This will generate a complete form with a file input and a submit tag. The form will contain all the necessary hidden fields to perform a direct upload to S3.

Configuration Options

Many of these options correspond to the HTML form fields that AWS accepts. This documentation will be helpful: http://docs.aws.amazon.com/AmazonS3/latest/dev/HTTPPOSTForms.html

All of these can be congured in an initializer, a yaml config file, or passed directly to the helper in a hash.

Option Description
:file Name of yaml file located in the config directory. Contains any of the options listed in this table. Should be set inside a configuration block via an initializer.
:s3_bucket AWS S3 bucket name where files will stored. Can also be configured via ENV['S3_BUCKET']. Required
:aws_access_key AWS Access Key. Can also be configured via ENV['AWS_ACCESS_KEY']. Required for buckets that are not public-write.
:aws_secret_key AWS AWS Secret Accss Key. Can also be configured via ENV['AWS_SECRET_KEY']. Required for buckets that are not public-write.
:key This is the key for the S3 object. To use the filename of the upload, use the vairable $filename (see example). Required
:acl Sepecies an S3 access control list. Valid values: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control. Default: private
:cache_control Refer to S3 PUT Object documentation
:content_disposition Refer to S3 PUT Object documentation
:content_encoding Refer to S3 PUT Object documentation
:expires Refer to S3 PUT Object documentation
:content_type A standard MIME type describing the format of the contents. Default: binary/octet-stream. Note: S3 will not automatically determine the content_type.
:success_action_redirect The URL to which a client is redirected after a successful upload. S3 will append the bucket, key, and etag as query parameters to the URL
:success_action_status HTTP status code returned upon successful upload if success_action_redirect is not set. Default: 204.
:min_file_size Size in bytes of minimum allowed file size Default: 0
:max_file_size Size in bytes of maximum allowed file size Default: 10485760
:amz_meta_tags Hash of additional metadata to be stored with the object. Stored on S3 as x-amz-meta-#{key} = #{value}
:minutes_valid Length of time in minutes that the generated form is valid. Default: 360
:form_html_options Hash of additional options that is passed to the form_tag contructor.
:file_field_tag_accept Sets the accept parameter of the file field tag. ?
:multiple_files Sets multiple=true for the file field input
:submit_tag HTML string containing code for the input or button that will handle form submission. This is optional and if not included a basic submit tag will be generated for the form.
:submit_tag_value Override the value of the standard generated submit tag. Default: "Upload"
:submit_tag_options Hash of options passed to the submit_tag generator.
:no_file_input When set to true, will not generate ae file field input. Useful when combined with form_fields_only
:form_fields_only Will generate only the form fields and not the form tag or the submit tag. Useful for customization.

Examples

coming soon.

Credits

With inspiration from:

License

Copyright © 2013 Lukas Eklund, released under the MIT license