capistrano/documentation/getting-started/cold-start/index.markdown

title	layout
Cold Start	default

At this point we should have a deploy user on all the servers we intend to deploy to, that user should have permission to write to wherever we plan on deploying to, by default that'll be something like /var/www/my-application.

We've set up the directory with decent permissions so that we can deploy without breaking things, and that everyone on our team can deploy, too.

Let's run through what we've done so far, and how to check it's all working, in the last step of this part of the guide we'll create the production-only shared files.

Again, this guide assumes Ruby on Rails, but most of everything we're doing so far is applicable in slightly modified forms to other frameworks and technologies.

1. Checking the directory structure on the remote machine:

{% prism bash %} me@localhost $ ssh deploy@remote 'ls -lR /var/www/my-application' my-application: total 8 drwxrwsr-x 2 deploy deploy 4096 Jun 24 20:55 releases drwxrwsr-x 2 deploy deploy 4096 Jun 24 20:55 shared

my-application/releases:
total 0

my-application/shared:
total 0

{% endprism %}

This checks in one simple command that the ssh keys you setup are working (you might yet be prompted for the password), and the permissions on the directory can be seen.

2. Writing our first cap task to formalize this into a check!

Now that we know how to check for permissions, and repository access, we'll quickly introduce ourselves to a quick Cap task to check these things on all the machines for us:

{% prism ruby %} desc "Check that we can access everything" task :check_write_permissions do on roles(:all) do |host| if test("[ -w #{fetch(:deploy_to)} ]") info "#{fetch(:deploy_to)} is writable on #{host}" else error "#{fetch(:deploy_to)} is not writable on #{host}" end end end {% endprism %}

Running this should give you a pretty decent overview, one line of output for each server. It's also your first introduction to the API of Capistrano for writing your own tasks, namely desc(), task(), on(), roles(), test(), info(), and error().

The first two methods, desc() and task() are actually from Rake, the library that forms the foundation of the Capistrano task system, the other methods are part of our sub-project SSHKit. We'll dive into those more later, but add those lines to a file in ./lib/capistrano/tasks, call it something like access_check.cap, and run cap -T from the top directory and we'll be able to see the task listed:

{% prism bash %} me@localhost $ bundle exec cap -T # ... lots of other tasks ... cap check_write_permissions # Check that we can access everything # ... lots of other tasks ... {% endprism %}

Then we simply call it:

{% prism bash %} me@localhost $ bundle exec cap staging check_write_permissions DEBUG [82c92144] Running /usr/bin/env [ -w /var/www/my-application ] on myserver.com DEBUG [82c92144] Command: [ -w /var/www/my-application ] DEBUG [82c92144] Finished in 0.456 seconds command successful. INFO /var/www/my-application is writable on myserver.com {% endprism %}

If we've done something wrong, that won't happen and we'll know that we need to jump on the mailing list to get help, or into IRC or ask a friend.

Depending how you have set your Git authentication credentials up, checking Git can be a bit complicated, so we've shipped a task in the core library that can check your git access, Git isn't particularly scriptable, so one has to wrap Git in a shell script that makes it behave.

Capistrano does just this, so to check if the Git access is working, we can simply call:

{% prism bash %} me@localhost $ cap staging git:check {% endprism %}

This task is defined here in the source code, and looks a lot like what we wrote above to check the file permissions, however the Git check recipe is a bit more complicated, having to potentially deal with three different authentication schemes, which need to be worked around differently. This task expresses a dependency on the git:git-wrapper task which is resolved first for us by Capistrano. (This is one of the pieces we inherit from Rake)

If this fails we'll see:

{% prism bash %} me@localhost $ cap staging git:check cap staging git:check DEBUG Uploading /tmp/git-ssh.sh 0% INFO Uploading /tmp/git-ssh.sh 100% INFO [118bd3e4] Running /usr/bin/env chmod +x /tmp/git-ssh.sh on example.com DEBUG [118bd3e4] Command: /usr/bin/env chmod +x /tmp/git-ssh.sh INFO [118bd3e4] Finished in 0.049 seconds command successful. INFO [a996463f] Running /usr/bin/env git ls-remote git@github.com:capistrano/rails3-bootstrap-devise-cancan.git on harrow DEBUG [a996463f] Command: ( GIT_ASKPASS=/bin/echo GIT_SSH=/tmp/git-ssh.sh /usr/bin/env git ls-remote git@github.com:capistrano/rails3-bootstrap-devise-cancan.git ) DEBUG [a996463f] Warning: Permanently added 'github.com,204.232.175.90' (RSA) to the list of known hosts. DEBUG [a996463f] Permission denied (publickey). DEBUG [a996463f] fatal: The remote end hung up unexpectedly cap aborted! git stdout: Nothing written git stderr: Nothing written

Tasks: TOP => git:check
(See full trace by running task with --trace)

{% endprism %}

This'll typically come out looking more beautiful depending on your terminal colour support, you may well see something like this:

To run through that shortly, what did we do:

1. We asked Capistrano to run the command git:check.
2. Capistrano recognised that in order to fulfil this request, it had first to execute the task git:wrapper, a prerequisite.
3. Capistrano exexuted the git:wrapper task, and uploaded the /tmp/git-ssh.sh file, and made it executable. This satisfies the git:wrapper task defined here in the source code. This script is actually processed as a template.
4. With the git wrapper in place, we can safely script against Git without it prompting us for input, so we ask git to ls-remote on the repository we defined. As this exited with an unclean status, Capistrano aborted, and printed out the erorr messages for us to try and figure out what broke.

In this case, we'll be using SSH agent forwarding, we can check if that's working by writing a tiny Cap task, or simply using SSH to do it for us, the choice is yours:

{% prism ruby %} # lib/capistrano/tasks/agent_forwarding.cap desc "Check if agent forwarding is working" task :forwarding do on roles(:all) do |h| if test("env | grep SSH_AUTH_SOCK") info "Agent forwarding is up to #{h}" else error "Agent forwarding is NOT up to #{h}" end end end {% endprism %}

That gave the output:

{% prism bash %} cap staging forwarding DEBUG [f1269276] Running /usr/bin/env env | grep SSH_AUTH_SOCK on example.com DEBUG [f1269276] Command: env | grep SSH_AUTH_SOCK DEBUG [f1269276] SSH_AUTH_SOCK=/tmp/ssh-nQUEmyQ2nS/agent.2546 DEBUG [f1269276] Finished in 0.453 seconds command successful. INFO Agent forwarding is up to example.com {% endprism %}

If you don't feel like writing a Capistrano task, one could simply do:

{% prism bash %} me@localhost $ ssh -A example.com 'env | grep SSH_AUTH_SOCK' SSH_AUTH_SOCK=/tmp/ssh-Tb6X8V53tm/agent.2934 {% endprism %}

If we see the SSH_AUTH_SOCK output, that's a pretty good indication that SSH agent forwarding is enabled, and if on your local machine ssh-add -l shows you an SSH key, then we're good to go. Make sure that you're using the git@... repository URL

{% prism bash %} cap staging git:check DEBUG Uploading /tmp/git-ssh.sh 0% INFO Uploading /tmp/git-ssh.sh 100% INFO [21382716] Running /usr/bin/env chmod +x /tmp/git-ssh.sh on example.com DEBUG [21382716] Command: /usr/bin/env chmod +x /tmp/git-ssh.sh INFO [21382716] Finished in 0.047 seconds command successful. INFO [f40edfbb] Running /usr/bin/env git ls-remote git@github.com:capistrano/rails3-bootstrap-devise-cancan.git on example.com DEBUG [f40edfbb] Command: ( GIT_ASKPASS=/bin/echo GIT_SSH=/tmp/git-ssh.sh /usr/bin/env git ls-remote git@github.com:capistrano/rails3-bootstrap-devise-cancan.git ) DEBUG [f40edfbb] 3419812c9f146d9a84b44bcc2c3caef94da54758 HEAD DEBUG [f40edfbb] 3419812c9f146d9a84b44bcc2c3caef94da54758 refs/heads/master INFO [f40edfbb] Finished in 3.319 seconds command successful. {% endprism %}