Capistrano authorization How-To

Cap has made our deployments simple, fast, and reliable. However, it can only access services you yourself have access to. Establishing this access for the first time can be a bit of a trick.

If you have previously deployed this project:

cap [STAGE] deploy

Have a beer; you're living the dream.

If it is your first deploy to a pre-existing destination:

Plan A should to ask your sysadmin for access. However, if you are the sysadmin, or there isn't one in the picture, here are some pointers. First, familiarize yourself with how SSH keys work.

All of the tasks that cap will need to perform can be verified manually. Unless otherwise noted, all commands should be run from your local box.

ssh deploy@destination.com

This should connect you to the host, without prompting for the password. If not, update ~/.ssh/authorized_keys on the destination.

ssh deploy@gateway.com ssh deploy@destination.com uname

If your server is accessed via a gateway (common in some production environments), this will test your connection through that gateway. Your key will need to be authorized on the gateway, on the destination, and (for some cap tasks) the deploy@gateway user's key must be authorized on the destination.

If you are setting up a new destination:

git ls-remote <repository>

Run this command from the destination host, while logged in as the deploy user. If it doesn't work you'll need to authorize the deploy user to access your repository. We use a special github account for this purpose.

touch [DEPLOY_TO]

This should also be run as the deploy user, and will verify you have write access to the appropriate directory (the directory, such as /var/www is specified by :deploy_to in your config file.)

cap [STAGE] deploy:setup

This will initialize the destination.

Troubleshooting

It's generally safe to attempt cap deploy iteratively. If it doesn't work, study the output and try to figure out what cap was trying to do when it failed. By repeating that step manually, you can often discover where the hang-up is.