Capistrano::Releases

This gem simplifies working with Auto scaling for AWS EC2 and Capistrano. It does this by storing your releases in AWS S3 and synchronizing them when needed (after deploy, instance reboot, and after a new instance is created).

Requirements

  • Ruby 2.X or greater
  • aws-sdk 2.X or greater
  • An AWS S3 bucket to store releases
  • Read and write API permissions to the S3 bucket
  • Capistrano installed and configured properly with deploys already working

Installation

Add this line to your application's Gemfile:

gem 'capistrano-releases'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-releases

Usage

It is assumed that you have already setup a S3 bucket and granted API read/write permissions to it. You should test to make sure your instances are able to read/write to the bucket before continuing.

You normally interact with the gem through the command line (see below for flag details):

$ releases --help

The general idea is that after each deploy, you 'push' the new release to S3. Then, after each boot (or reboot) your instances 'pull' the latest releases from S3.

For 'push' you need to edit your deploy.rb and add something like this:

namespace :releases do
    bucket = 'your-bucket-name-goes-here'

    desc 'Push releases'
    task :push do
        on roles(:all, primary: true) do
            execute "releases -b #{bucket} -d #{fetch(:deploy_to)} -m push"
        end
    end
end
after 'deploy:finished', 'releases:push'

For 'pull' you need to configure your server to run a command before your Rails processes (Puma, Thin, Sidekiq, etc) start:

$ releases -b your-bucket-name-goes-here -d /your/deploy/to/name/goes/here -m pull

You must now write a boot script for your Rails processes. These tend to be very specific to your environment and the set of Capistrano gems you are using. An example is provided below.

Flags

--mode

You must pick a mode to run in: 'push' or 'pull'.

The push mode compare your local releases to those stored in S3. Any missing releases will get compressed and uploaded. The 'current' symlink version will also get uploaded.

The pull mode compares the releases stored in S3 to your local releases. Any missing releases will get downloaded and uncompressed. Finally, the 'current' symlink will get updated to match the remote version.

--bucket

Your instances must have read/write access to the specified S3 bucket. Make sure your instances have the correct permissions with an IAM role or make sure you specify the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. Under the hood this gem uses the aws-sdk gem for all API calls.

--deploy-to

This flag must be set to match the Capistrano configuration variable of the same name. You can normally find it in your deploy.rb. An example from a stock config:

set :deploy_to, "/var/www/my_app_name"

Rails boot script

This is just a sample. You will need to modify it based on your Capistrano configuration. Watch the commands that are executed when you run cap production deploy to see what commands are executed. Also make sure you run it as :deploy_user as specified in your deploy.rb.

#!/bin/bash

echo '***** pulling releases *****' &&
releases -b my-releases-bucket -d /apps/my-app -m pull &&

echo '***** Deleting old PID files *****' &&
rm -rf /apps/my-app/shared/tmp/pids/* &&

echo '***** Installing gems *****' &&
bundle install --path /apps/my-app/shared/bundle --without development test --deployment --quiet &&

echo '***** Precompiling assets *****' &&
bundle exec rake assets:precompile &&

echo '***** Starting web server *****' &&
echo 'put your web server command here' &&

echo '***** Starting job server *****' &&
echo 'put your job server command here'

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/chadrem/capistrano-releases.

License

The gem is available as open source under the terms of the MIT License.