Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Using Ruby and Capistrano, build and deploy a static website to Amazon S3
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


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

Hosting your website with Amazon S3

S3 provides special website enabled buckets that allows you to deliver website pages directly from S3. The most important difference is that theses buckets serves an index document (ex. index.html) whenever a user specifies the URL for the root of your website, or a subfolder. And you can point your domain name directly to the S3 bucket cname.

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

Getting started

Setup capistrano, create a public folder and set your S3 bucket configurations in deploy.rb.

$ capify .
$ mkdir public
$ touch config/deploy.rb #see config instructions bellow
$ cap deploy

Configuring deployment

s3-static-site overrides the default Capistrano recipes for Rails projects with its own simple s3 publishing scripts.

# config/deploy.rb
require 's3-static-site'

set :bucket, ""
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.

S3 write options

s3-static-site 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 S3Object.write doc for all available options.

Built-in HAML template rendering and SASS compile

On deployment, .haml and .sass are generated and uploaded (source .haml and .sass are not uploaded).

Advanced static website generation & assets management

If you wish to manage your assets with a packaging system, a simple way do to it is using a combination of :

  • Sinatra : simple web framework that we extend for our needs
  • Sinatra-AssetPack : deals with version management for all kind of assets
  • Sinatra-Static : generate your complete website in public/, allowing an s3-static-site deployment

IMPORTANT : to achieve Sinatra-AssetPack and Sinatra-Static compatibility, see pull request #1 or use a patched fork.

Once you get this together, add a capistrano task to trigger website generation before deploy :

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


Copyright (c) 2012 Josh Delsman & miomoba, Inc. See LICENSE.txt for details.

Something went wrong with that request. Please try again.