Skip to content

Latest commit

 

History

History
65 lines (50 loc) · 4.09 KB

README.markdown

File metadata and controls

65 lines (50 loc) · 4.09 KB
Raw

A BrowserCMS module to allow storage of images and files on the Amazon S3 storage facility

Using S3 for file storage

To enable S3 file storage set Cms::S3.enabled in config/initializers/browsercms.rb (create this if it does not exist) to true. Ensure that you as provide a s3.yml file that contains your credentials and bucket. This should be in the following format

access_key_id: your AWS access key
secret_access_key: your AWS secret access key
bucket: your unique bucket name

Using this module with Heroku

If using this module in conjunction with deployment on heroku you should probably turning heroku caching on by setting Cms::S3.heroku_caching in config/initializers/browsercms.rb to true.

In order to avoid putting your secret AWS key in the s3.yml file, you can take advantage of heroku's config vars. Use ERB to read the values from the environment. This way you can safely commit your s3.yml file to the repository without revealing your amazon credentials.

access_key_id: <%= ENV['s3_access_key_id'] %>
secret_access_key: <%= ENV['s3_secret_access_key'] %>
bucket: <%= ENV['s3_bucket'] %>

For developing on your local machine, export the s3 variables to your environment.

export s3_access_key_id='your AWS access key'
export s3_secret_access_key='your AWS secret access key'
export s3_bucket='your unique bucket name'

Set the config vars on heroku to get it working there as well.

heroku config:add s3_access_key_id='your AWS access key'
heroku config:add s3_secret_access_key='your AWS secret access key'
heroku config:add s3_bucket='your unique bucket name'

www prefix for non cms urls

If your non cms domain is www.myapp.com rather than app.com this can be enabled by setting Cms::S3.www_domain_prefix in config/initializers/browsercms.rb to true.

using cnames to your S3 bucket

If you've set up CNAMES in your DNS to point to your bucket, then you can enable the use of that instead of the FQDN ending in amazonaws.com by setting Cms::S3.options[:s3_cname] in your s3.yml file.

Important things to note

  1. The s3.yml should be excluded from public repositories (e.g github) since it contains your secret AWS key which should never be revealed to the public.
    Please note. This no longer applies since the access keys and buckets are now specified in environmental variables and therefore the s3.yml file now contains just references to these environmental variables (hopefully).
  2. Changing from local storage to S3 storage will require you to re-upload all your files (or copy the tree to s3)
  3. This module requires the RightAWS gem from RightScale (sudo gem install right_aws)
Based on original work on S3 storage for BrowserCMS by Neil Middleton

Important note for use with Rails 3 and BCMS 3.1.x-axes

Due to the use of 3.4+'s Engines, I can't work out how to extend the Cms::AttachmentsController and Models from within the module, so you will need to add the block below in the initializer for browsercms.rb

Cms::AttachmentsController.send(:include, Cms::S3::AttachmentsController)
Cms::ContentController.send(:include, Cms::S3::ContentController)
#browsercms 3.4 require any references to core BrowserCMS classes to have a Cms:: added to them (namespace goodness :P)
Cms::Attachment.send(:include, Cms::S3::Attachment)
Cms::ApplicationController.send(:include, Cms::S3::ApplicationController)
# ensure S3 storage disabled by default
Cms::S3.enabled = false if Cms::S3.enabled.nil?
# ensure heroku caching disabled by default
Cms::S3.heroku_caching = false if Cms::S3.heroku_caching.nil?
# function to set domain prefix without url to 'www' is disabled by default
Cms::S3.www_domain_prefix = false if Cms::S3.www_domain_prefix.nil?
# load s3 options if s3.yml exists
if File.exists?("#{Rails.root}/config/s3.yml")
  yaml_string = IO.read("#{Rails.root}/config/s3.yml")
  Cms::S3.options =  YAML::load(ERB.new(yaml_string).result)
  Cms::S3.options.symbolize_keys!
end