Who this guide is for

This guide is aimed at developers who already have a working Rails application with a Capistrano recipe ready. If you are just starting with Capistrano and need help with your first recipe, check out our guide on the topic first. Before you get started, make sure you have a Beanstalk account.

Why use Beanstalk to deploy with Capistrano?

While Capistrano is an awesome performer for deployments, it was never meant to be a manager for them. Out of the box it doesn’t notify your team members about deployments; it doesn’t allow you to specify what users from your team can deploy to which environments; doesn’t allow you to view history of deployments, and so forth. Plus it requires a custom installation on each computer from which deployments are going to be triggered. This makes it impossible to deploy from mobile devices or unprepared computers.

Using Beanstalk to trigger Capistrano deployments solves all of these problems. You can use the full power and flexibility of Capistrano, coupled with a streamlined deployment process and the ease of use of Beanstalk. Deploy notifications, permissions, historic timeline, auto-deployments on each commit/push – you get it all. And you can deploy from any device that has internet and a web browser, no setup required.

How does it work?

The plan is simple. We still want to run our usual Capistrano recipe, but instead of doing it by hand on our local computer, we will ask Beanstalk to SSH to one of our servers (let’s call it a gateway server) and run the Capistrano recipe there for us. You can use any server from your stack for that role, just make sure it’s available from the outside for Beanstalk to connect to. If you only have one server, then it will simply deploy to itself, no big deal.

Setting up a gateway server

Find a machine that’s capable of being a gateway server in your stack, then prepare to run your Rails application on it. There’s no need to have all dependencies installed on that box, you just have to be able to execute cap deploy from there. You can even use a separate group in your Gemfile to install only gems that are required by your Capistrano recipe.

The next step is to make sure that all of the servers from your Capistrano recipe are reachable from the gateway server. Try connecting to all of the servers by hand and see if they work. You might need to add the gateway’s SSH key to the servers to ensure authentication. If some servers are unreachable, your deployment in Beanstalk will fail.

After that is done, you can setup a server in Beanstalk. First create an environment, then add an SSH server to it. Set the Working Directory in the settings to the directory where the Rails application on your server is located to make sure that your SSH commands are executed in the right context.

SSH commands

Here are the commands that we will use to deploy our app to staging:

git checkout staging -f
git pull origin staging
bundle install --deployment --without test
bundle exec cap staging deploy:migrations -s revision=%REVISION%

Most likely you will need to adjust these commands to fit your needs, but generally the workflow should remain the same.

This specific set of commands ensures a few things:

• You are always deploying from the staging branch (if it’s a staging environment, of course)
• The branch is always up to date
• Your bundle, which is responsible to provide Capistrano and it’s plugins, is complete
• Your migrations are always executed
• The revision that you specified in Beanstalk during deploy is passed to Capistrano

All of this ensures that if you decide to rollback from Beanstalk, Capistrano will deliver.

Real-time Transfer Log

If you set everything up correctly, at this point you should be able to issue a Capistrano deployments from Beanstalk. Staging deployments can be triggered automatically on every push, while Production can be deployed with a hit of a button. No need to mess with command line and rake tasks anymore.

You can watch the execution of your Capistrano recipe, line-by-line, in Transfer Log in real time. This way if something goes wrong with a mission critical deployment you will see it right away.