Deploy with Capistrano

To prepare your project for Capistrano, go into the root directory of that project and run capify:

$ cd my_project
$ capify .

Generate Public Key

It would probably be a good idea to add a special user on your server(s) specifically for deployment. Once created, make sure to generate a public key for the server and add it to your github account. You may also want to add your personal public key to this new user’s ~/.ssh/authorized_keys to ease deployment.

For more help with deploy keys, see this guide.

Settings

Here are the 5 most notable Capistrano config options (found in deploy.rb):

default_run_options[:pty] = true  # Must be set for the password prompt from git to work
set :repository, "git@github.com:vanpelt/rails-app.git"  # Your clone URL
set :scm, "git"
set :user, "deployer"  # The server's user for deploys
set :scm_passphrase, "p@ssw0rd"  # The deploy user's password

Agent Forwarding

If you’re using your own private keys for git you might want to tell Capistrano to use agent forwarding with this command. Agent forwarding can make key management much simpler as it uses your local keys instead of keys installed on the server.

ssh_options[:forward_agent] = true

Set Branch

You need to tell cap the branch to checkout during deployment:

set :branch, "master"

Older versions of cap need the full branch name:

set :branch, "origin/master"

Older versions of git (e.g. 1.4.4.2) don’t support git checkout -q, this will cause your deployment to fail. To fix either upgrade git or:

set :scm_verbose, true

Remote Cache

In most cases you want to use this option, otherwise each deploy will do a full repository clone every time.

set :deploy_via, :remote_cache

Remote caching will keep a local git repo on the server you’re deploying to and simply run a fetch from that rather than an entire clone. This is probably the best option as it will only fetch the changes since the last.

Shallow Clone

As an alternative to the remote cache approach, you can use shallow cloning.

set :git_shallow_clone, 1

Shallow cloning will do a clone each time, but will only get the top commit, not the entire repo. This makes it a bit closer to how an svn checkout works. Be warned, shallow clone won’t work well with the set :branch option.

Submodules

If you’re using git submodules you must tell cap to fetch them.

set :git_enable_submodules, 1

Migrating from SVN

Migrating from SVN-based deploys? Check this thread if you run into any problems.

Known Hosts bug

If you are not using agent forwarding, the first time you deploy may fail due to Capistrano not prompting with this message:

The authenticity of host 'github.com (207.97.227.239)' can't be established.
RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48.
Are you sure you want to continue connecting (yes/no)?

To fix this, ssh into your server as the user you will deploy with, run ssh git@github.com and confirm the prompt.