Capistrano 2 to Capistrano 3 upgrade

Now that Capistrano 3 is available, it is time to upgrade your capistrano deployment setup.

It is recommended to backup your old capistrano files to a directory

mkdir old_capistrano

mv Capfile config/deploy.rb old_capistrano

cd project_dir

Instead of running

capify .


cap install

This should create following files




By default, this should create staging and production stage files

You can move your stage specific settings to the stage file

Variables can be set with the set command but unlike Capistrano version 2, you need to use fetch(:attribute) to fetch the attribute value

If you are using the same domain for web, app and db, you can now use

set :domain, ''

roles :all,  fetch(:domain)

If you were using default_run_options in Capistrano 2 for setting pty option, you now need to use

set :pty, true

set :repository, 'your_repository_url' should be converted to

set :repo_url, 'your_repository_url'

If ssh authorisation was working with Capistrano 2 and starts throwing SSH Authorisation issues, adding your user in ssh options should fix this in most cases. Do so by setting ssh_options

set :ssh_options {

user: 'your user',

verbose: :debug # add this to find exact issue when your deployment fails


You should move all your common settings to deploy.rb which can then be used in all stages.

The number of releases directories that you want on the server can be configured using

set :keep_releases, 10 # default is 5.

You should be able to find much more information here

and here

Guess it is time for another update and another deployment ..


5 thoughts on “Capistrano 2 to Capistrano 3 upgrade

  1. How do you set ssh_keys???? Deploying to AWS seems impossible now; even with this format. It used to be:

    ssh_options[:keys] = [‘~/.ssh/awskey.pem’]

    Now just gone???

    cap deploy:production
    cap aborted!
    config/deploy.rb: syntax error, unexpected ‘{‘, expecting end-of-input


    set :ssh_options {
    keys: ‘~/.ssh/awskey.pem’, # Path to your aws keypair on local machine

    same error 😦

    1. I am not sure about pem files but you could try adding the auth_methods for the key.
      Could you try adding the auth_methods like this.
      ssh_options: {
      user: ‘user_name’,
      keys: %w(/home/user_name/.ssh/id_rsa),
      forward_agent: false,
      auth_methods: %w(publickey)

      Or you could take a look at this gem ..

      Hope it helps

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s