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.
The following command will install the latest released capistrano
$ 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
capistrano-rails gem includes extras specifically designed for Ruby on
- Asset Pipeline Support
- Database Migration Support
The documentation for these components can be found in
READMEs. However for the most
part, to get the best, and most sensible results, simply
Capfile, after the
require 'capistrano/deploy' line:
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
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
~/.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
by mistake, then you can lock your Gem version for Capistrano at something
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
2.15.4, and any other point-release in the
2.15.x family without
the risk of accidentally upgrading to