Deploying your web app to multiple environments (e.g. development, test, production) is a cinch using Capistrano. Let me show you how.

Capistrano is written in Ruby, so this is your main pre-requisite. Get Ruby and Rubygems installed, and then simply type the following command to install the Capistrano gem:

gem install capistrano

Getting your application ready for deployment starts with the following command, issued from inside your app’s top-level directory:

capify .

This two files: Capfile and config/deploy.rb. The latter is where we are going to tell Capistrano how we want it to deploy our application.

set :application, "myapp"
set :repository,  "git@github.com:johngrimes/myapp.git"
set :scm, "git"

The first part of our deploy.rb gives our app a name and tells Capistrano where to pull the latest copy of our app from. This example has us using Github as our source code repository.

task :to_dev do
  set :user, "webadmin"
  set :runner, "webadmin"
  role :web, "dev.myapp.com"
  set :deploy_to, "/var/www"
end

task :to_test do
  set :user, "webadmin"
  set :runner, "webadmin"
  role :web, "test.myapp.com"
  set :deploy_to, "/var/www"
end

task :to_prod do
  set :user, "webadmin"
  set :runner, "webadmin"
  role :web, "myapp.com"
  set :deploy_to, "/var/www"
end

The next part of our script sets up a task for each of the environments that we might want to deploy to. These tasks do not actually perform any actions: they simply set the server and location for deployment, along with the users that our script should use to connect to the server via SSH and run our tasks.

And that’s it! The script we have written so far will deploy your application in the default Capistrano manner. Before we do so, however, we need to set up our deployment area for the first time:

cap deploy:setup
cap deploy:check

The first command will set up the default Capistrano deployment directory structure on the server, then the second command will check for all the required dependencies for a successful deployment (write permissions, git is installed, etc.). Once this is all ok, use you can the following commands for deploying to development, test and production respectively:

cap to_dev deploy
cap to_test deploy
cap to_prod deploy

I like to add a few extra bits to customise the deployment process a bit.

after :deploy, 'create_symlinks'
after :deploy, 'set_permissions'
after :deploy, 'deploy:cleanup'

task :create_symlinks do
  # Create symbolic link to a common database.yml which
  # is not under source control

  run "ln -nfs #{shared_path}/system/config/database.yml
    #{release_path}/config/database.yml"
end

task :set_permissions do
  # Change the owner and group of everything under the
  # deployment directory to webadmin and apache
  run "chown -R webadmin:apache #{deploy_to}"
end

task :after_setup, :roles => :web do
  set_permissions
end

This code instructs Capistrano to reset the owner and group of everything under our deployment directory after each deployment. This is useful for making sure that key directories are writable by our webserver.

It also ‘cleans up’ old deployments each time, by removing everything bar the last 5 deployments.

You also might want to create other tasks that are performed after each deployment, such as the one shown above for creating a symbolic link to a file that is located elsewhere on the server and not kept in source control.

Something to keep in mind is that for Capistrano deployment to work, you need to check the following things:

• the computer you are running the deployment from can access the server(s) via SSH
• the server(s) can access the source code repository

I find that the best (and most automated) way of doing this is by setting up SSH authentication keys so that your deployment scripts can achieve password-less login. This article will show you how to do it for the SSH from your machine to the server, and this article will show you how to set up keys for your Github account.