But if you run into problems it can be a bear to troubleshoot. And the documentation is not great.
One issue that can catch you (or me!) unawares is the 'run' command that runs a Unix command on the remote host. I use these to symlink various files and to start up a daemon on the new deployment once that is complete.
You run into a problem if any of your remote commands require access to your Unix Environment Variables. The 'run' command is executed in a minimal environment without any of these.
The solution is to specify the variables that you need, such as PATH, as key/value pairs in the 'default_environment' hash in your cap deploy.rb file.
For example, here are two variables defined near the top of my file:
default_environment['AMAZON_ACCESS_KEY_ID'] = "YourAwsKeyHere"
default_environment['AMAZON_SECRET_ACCESS_KEY'] = "YourSecretAccessKeyHere"
Easy enough, once you know... not at all easy if you don't know!