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.

leklund/s3lurp

s3lurp - Browser Uploads Direct to S3

Installation

Configuration

AWS S3 Setup

S3lurp Config Example

Configuration Options

Examples

Credits

License