capistrano-s3

Enables static websites deployment to Amazon S3 website buckets using Capistrano.

Hosting your website with Amazon S3

Amazon S3 provides special websites enabled buckets that allows you to serve web pages from S3.

To learn how to setup your website bucket, see Amazon Documentation.

Getting started

# Gemfile
source 'https://rubygems.org'
gem 'capistrano-s3'

Setup

Install gems with bundle and create your public folder that will be published :

bundle install
mkdir -p public

Gem supports both flavors of Capistrano (2/3). Configurations between versions differ a bit though.

Capistrano 2

First initialise Capistrano for given project - bundle exec capify .

Replace deploy.rb content generated by capify with these simple Amazon S3 configurations :

# config/deploy.rb
require 'capistrano/s3'

set :bucket,            "www.cool-website-bucket.com"
set :access_key_id,     "CHANGETHIS"
set :secret_access_key, "CHANGETHIS"

If you want to deploy to multiple buckets, have a look at Capistrano multistage and configure a bucket per stage configuration.

Capistrano 3

Initialise Capistrano by running - bundle exec cap install

Next add require "capistrano/s3" to Capfile.

Finally, replace deploy.rb content generated by Capistrano with this config:

# config/deploy.rb
set :bucket,            "www.cool-website-bucket.com"
set :access_key_id,     "CHANGETHIS"
set :secret_access_key, "CHANGETHIS"

Deploying

Add content to your public folder and run deploy command:

cap deploy (Capistrano 2)

cap <stage> deploy (Capistrano 3).

Advanced options

Custom endpoint

If your bucket is not in the default US Standard region, set endpoint with :

set :s3_endpoint, 's3-eu-west-1.amazonaws.com'

Write options

capistrano-s3 sets files :content_type and :acl to :public_read, add or override with :

set :bucket_write_options, {
    cache_control: "max-age=94608000, public"
}

See aws-sdk S3Client.put_object doc for all available options.

Redirecting

Use :redirect_options to natively redirect (via HTTP 301 status code) any hosted page. For example:

set :redirect_options, {
  'index.html' => 'http://example.org',
  'another.html' => '/test.html',
}

Valid redirect destination should either start with http or https scheme, or begin with leading slash /.

Example of usage

Our Ruby stack for static websites :

sinatra : awesome simple ruby web framework
sinatra-assetpack : deals with assets management, build static files into public/
sinatra-export : exports all sinatra routes into public/ as html or other common formats (json, csv, etc)

Mixing it in a capistrano task :

# config/deploy.rb
before 'deploy' do
  run_locally "bundle exec ruby sinatra:export"
  run_locally "bundle exec rake assetpack:build"
end

See our boilerplate sinatra-static-bp for an example of the complete setup.

Contributing

See CONTRIBUTING.md for more details on contributing and running test.

Credits

capistrano-s3 is maintained and funded by hooktstudios

Thanks & credits also to all other contributors.

gevans / capistrano-s3