Introduction

Capistrano is a Ruby program that gives you a set of advanced tools to deploy web applications to your servers. In its simplest form, Capistrano allows you to copy code from your source control repository (SVN or Git) to your server via SSH, and perform pre and post-deploy functions like restarting a webserver, busting cache, renaming files, running database migrations and so on. With Capistrano it’s also possible to deploy to many machines at once.

Capistrano offers many advanced options that won’t be covered in this guide, and can be used to deploy many kinds of applications. For learning purposes, we will take you through the steps to setup a simple recipe for deploying a Rails application to a single server from either SVN or Git repositories. We will cover a common workflow that allows you to deploy multiple environments: in this case, staging and production.

How to Install Capistrano

In order to install Capistrano you will need Ruby and RubyGems installed on your computer. If you’re on a Mac running macOS 10.5+, you’re ready to go. If not, you can use this reference to learn how to install Ruby and RubyGems.

Then, run the following command from a Terminal or command line:

gem install capistrano

For this guide, we recommend the handy capistrano-ext gem that contains an extra set of tools to make your deployments even easier:

gem install capistrano-ext

If you’re having trouble or would like more detailed documentation, you might want to reference the official Capistrano getting started guide, or find out more about the various components that make Capistrano work.

Server Dependencies

It’s important to make sure that your server is POSIX-compilant and has SSH access. Don’t forget to setup your SSH keys (Mac or Windows). If you can’t SSH into your server, Capistrano isn’t going to work for you.

Prepare your Project for Capistrano

Navigate to your application’s root directory in Terminal and run the following command:

capify .

This command creates a special file called Capfile in your project, and adds a template deployment recipe at config/deploy.rb in your Rails project. The Capfile helps Capistrano load your recipes and libraries properly, but you don’t need to edit it for now.

Instead, open the deploy.rb file in your favorite text editor. This file is where all the magic happens! You can start by deleting everything in the template file, as this guide will help you fill it with the correct code for a successful deployment recipe.

Working with Capistrano Recipes

How to Create a Capistrano Recipe

In your now-empty deploy.rb file, let’s enter the name of your app in the first line. If your app’s name is “fancy shoes”, you’d type:

set :application, "fancy_shoes"

Now let’s add a repository to access. Git users can add this:

set :scm, :git
set :repository, "git@account.git.beanstalkapp.com:/account/repository.git"
set :scm_passphrase, ""

And Subversion users can use this:

set :scm, :subversion
set :repository, "https://account.svn.beanstalkapp.com/repository"

Additionally let’s set the user on our server that we want Capistrano to run commands with:

set :user, "server-user-name"

Make sure that this user has read & write access to the directory that you specified in the deploy_to variable.

Before you go further, try connecting to that repository by hand from your Terminal (try an svn co or git clone), to make sure that you can authenticate properly. If you can’t connect to the repository, neither can Capistrano.

Next we’ll add information about your server to the recipe. We will be using the Capistrano Multistage function (it comes along with the gem capistrano-ext we installed earlier). This allows you to setup one recipe to deploy your code to more than one location. In this example, we’ll deploy to staging and production environments.

Begin by including multistage at the top of your deploy.rb file:

require 'capistrano/ext/multistage'

Then specify your environments, or “stages”:

set :stages, ["staging", "production"]
set :default_stage, "staging"

Since you will likely be deploying to staging more often than production, we find that it’s helpful to make staging the default stage. Next, create a directory called deploy inside your app’s config directory, and then add production.rb and staging.rb files to it. You’ll need one Ruby file per stage you’ve configured, and they need to be named the same so that Capistrano can load the appropriate files when you specify which stage you want to deploy.

Now let’s populate our production.rb settings:

server "my_fancy_server.com", :app, :web, :db, :primary => true
set :deploy_to, "/var/www/fancy_shoes"

And then staging.rb:

server "my_fancy_server.com", :app, :web, :db, :primary => true
set :deploy_to, "/var/www/fancy_shoes_staging"

In this example, we have only one server being assigned all three roles (app, web and db). The difference between production and staging is in the different deploy_to directory variables. In reality you might want to use different servers too.

Validating your Recipe

Everything is ready to try our recipe for the first time and let Capistrano create the initial directory structure on your server for future deployments. Run the following command from the root directory of your application:

cap deploy:setup

When you run this command, Capistrano will SSH to your server, enter the directory that you specified in the deploy_to variable, and create a special directory structure that’s required for Capistrano to work properly. If something is wrong with the permissions or SSH access, you will get error messages. Look closely at the output Capistrano gives you while the command is running.

The last step before we can do an actual deployment with Capistrano is to make sure that everything is set up correctly on the server from the setup command. There’s a simple way to verify, with the command:

cap deploy:check

This command will check your local environment and your server and locate likely problems. If you see any error messages, fix them and run the command again. Once you can run cap deploy:check without errors, you can proceed!

Deploy Using your New Recipe

Once you’ve verified your local and server configuration, run the following command:

cap deploy

This will perform a deployment to your default stage, which is staging. If you want to deploy to production, you’d run the following:

cap production deploy

While these commands are performed, you will see a lot of output. Capistrano print all commands it runs on your server as well as their output, making it possible for you to debug any problems.

Tips & Tricks

Improve Performance with Remote Cache

The way Capistrano works, it will create a new clone/export of your repository on every deploy. That can be slow, so there’s an option to add some extra commands to our deploy.rb recipe to speed things up. Add the following to the section of your deploy.rb where you describe your scm settings:

set :deploy_via, :remote_cache

This command makes Capistrano do a single clone/checkout of your repository on your server the first time, then do an svn up or git pull on every deploy instead of doing an entire clone/export. If you deploy often, you’ll notice that this speeds up your deployments significantly.

Add Custom Deploy Hooks

Capistrano shines by doing things more sophisticated than just copying files via SSH. You can configure events and commands to run after the copying of files completes, such as restart a web-server or run a custom script. Capistrano calls these “tasks”. For an example, add the following code to your deploy.rb file:

namespace :deploy do
  task :restart, :roles => :web do
    run "touch #{ current_path }/tmp/restart.txt"
  end

  task :restart_daemons, :roles => :app do
    sudo "monit restart all -g daemons"
  end
end

Tasks in Capistrano are very powerful, and we’re only scratching the surface in this guide. You can create tasks to perform operations on your server before, after or separately from your deployment. This can be any sort of maintenance: restarting processes, cleaning up files, sending email notifications, running database migrations, executing scripts, and so on.

Our example includes two custom tasks. The “restart” task is built into Capistrano and will be executed by Capistrano automatically after your deployment is complete. We use the touch tmp/restart.txt technique that’s common to modern Rails applications powered by Passenger, but your webserver may require a different command.

Our second example task is "restart_daemons", a custom task that Capistrano won’t run by default. We need to add a hook for it in order for it to run:

after "deploy", "deploy:restart_daemons" 

This command tells Capistrano to execute our task after all deploy operations are complete. Other hooks are available, including “before” which runs the task before the files are copied.

You can read more about before and after hooks in the official Capistrano documentation:

• Before Tasks
• After Tasks

Associate Git Branches With Environments

Since we have two server environments (staging and production) most likely you will want to bind your branches in Git to these environments, so that you can deploy staging branch to staging environment and master branch to production automatically. Simply add the following line to your production.rb:

set :branch, 'production'

And the following line to staging.rb:

set :branch, 'staging'

Now every time you run a cap deploy Capistrano will deploy code from your staging branch (since staging is our default environment). If you run cap production deploy Capistrano will deploy code from your master branch. Easy peasy!

Further Reading

Hopefully our guide was helpful for you as an initial kick-start. You will definitely want to read more, so we suggest you to go to the official wiki of Capistrano and read. You can start with their awesome From The Beginning article.