Capistrano SSH Doctor
This plugin helps you setup and debug
ssh-agent forwarding for Capistrano
It's created to complement the official capistrano authentication guide.
The following is presumed:
- you're using
- you want to use passwordless ssh to login to the servers
- you want to use the
ssh-agentforwarding strategy for checking out code in the remote repository (btw. good choice, it's a least hassle)
The plugin will report errors (and offer steps to solution) if you deviate from this configuration. The above assumptions should hold true for 98% users.
capistrano-ssh-doctor works only with Capistrano 3+.
Who should use it?
The plugin is made for beginners and users that are not sure if their setup is good, so they want to confirm or debug it.
Put the following in your application's
group :development do gem 'capistrano', '~> 3.2.1' gem 'capistrano-ssh-doctor', '~> 1.0' end
Then run in the console:
$ bundle install
Put the following in
This plugin is intended to be used before any deployment task.
In the console run:
$ bundle exec cap production ssh:doctor
A number of checks will be performed and you'll get a report at the end.
In case there are errors in your setup, specific instructions for next steps will be provided in report output.
Important: errors should be tackled in the order of their output. So, if you get errors 2, 5 and 7 in the report, start by solving error 2.
It is very probable that "solving" one or two initial errors will actually make everything work. A lot of the checks are inter-dependent. So don't be discouraged if you see a lot of the errors in the beginning.
Once you solved a problem, run the
ssh:doctor task again to see the
Repeat the process until
ssh:doctor task reports success for all the
tasks. You're ok with proceeding with the deployment then.
Which checks are performed?
- checks that you're using
- checks that ssh private key file exists locally
- checks if
ssh-agentprocess is running locally
- checks that
ssh-addprocess can communicate with
- checks that ssh private keys are loaded to
- checks that remote code repository is accessible from local machine
- checks passwordless ssh login is used for all servers
forward_agentcapistrano option is set to
truefor all servers
ssh-agentis actually forwared to all the servers
- checks remote code repository is accessible from all the servers
You'll see the results for all the checks in the output of
More Capistrano automation?
Check out capistrano-plugins github org.
Contributing and bug reports
If you got stuck at some point and really can't find a solution, please open a github issue and maybe I can help. Also, your problem can be used to improve this plugin and help others.