capistrano logo

Installation

Capistrano is bundled as a Ruby Gem. It requires Ruby 2.0 or newer.

Capistrano can be installed as a standalone Gem, or bundled into your application.

It is recommended to fix the version number when using Capistrano, and is therefore recommended to use an appropriate bundler.

General Usage

The following command will install the latest released capistrano v3 revision:

$ gem install capistrano

Or grab the bleeding edge head from:

$ git clone https://github.com/capistrano/capistrano.git
$ cd capistrano
$ gem build *.gemspec
$ gem install *.gem

Usage in a Rails project

Add the following lines to the Gemfile:

group :development do
  gem "capistrano", "~> 3.10", require: false
  gem "capistrano-rails", "~> 1.3", require: false
end

The capistrano-rails gem includes extras specifically designed for Ruby on Rails, specifically:

  • Asset Pipeline Support
  • Database Migration Support

The documentation for these components can be found in their, respective, READMEs. However for the most part, to get the best, and most sensible results, simply require in Capfile, after the require 'capistrano/deploy' line:

require 'capistrano/rails'
SSH

Capistrano deploys using SSH. Thus, you must be able to SSH (ideally with keys and ssh-agent) from the deployment system to the destination system for Capistrano to work.

You can test this using a ssh client, e.g. ssh myuser@destinationserver. If you cannot connect at all, you may need to set up the SSH server or resolve firewall/network issues. Look for a tutorial (here are suggestions for Ubuntu and RedHat/CentOS).

If a password is requested when you log in, you may need to set up SSH keys. GitHub has a good tutorial on creating these (follow steps 1 through 3). You will need to add your public key to ~/.ssh/authorized_keys on the destination server as the deployment user (append on a new line).

More information on SSH and login is available via the Authentication and Authorisation section of the guide.

If you are still struggling to get login working, try the Capistrano SSH Doctor plugin.

Help! I was using Capistrano v2.x and I didn’t want to upgrade!

If you are using Capistrano v2.x.x and have also installed Capistrano v3 by mistake, then you can lock your Gem version for Capistrano at something like:

gem 'capistrano', '~> 2.15' # Or whatever patch release you are using

This is the pessimistic operator which installs the closest matching version, at the time of writing this would install 2.15.4, and any other point-release in the 2.15.x family without the risk of accidentally upgrading to v3.

Fork me on GitHub