Capistrano has its own vocabulary that distinguishes it from simply being an extension of Rake, on which it is based:

The first time I sat down to use Capistrano, I asked myself: What do I need to do to use Capistrano? What does it expect of my app? Of my server? And when a deployment is finished, what has Capistrano done and what hasn’t it?

The following sections answer these questions and should set in place the larger view of Capistrano in your project development workflow.

When you’re done getting Capistrano and its requirements addressed (either directly or through customization), you’re left in deployment Nirvana. Okay, that’s a little strong, but your code will be deployed from your repository, migrations run, Apache and your app server (Mongrel, fastcgi) will be booted, and well... now you’re deployed, and ready for that next deployment event.

So now you can start doing great things like updating your servers with the latest svn check-in using cap deploy:update, or go full out and update to the latest release and restart your app servers using cap deploy. You can even put up a maintenance page during extended downtime using cap deploy:web:disable, and roll back when you mess up a deployment, using cap deploy:rollback.

If you’ve got multiple servers to manage, the commands don’t change, just your setup. Just a little config-file tweaking and you’re using cap deploy and cap deploy:invoke to run arbitrary commands on all servers simultaneously.

To get started, let’s install Capistrano:

$ sudo gem install capistrano
Install required dependency net-ssh? [Yn]
Install required dependency net-sftp? [Yn]
Install required dependency highline? [Yn]

Successfully installed capistrano-2.0

Running cap with the --tasks switch will tell us what tasks Capistrano knows about.

$ cap --tasks
cap invoke #Invoke a single command on the remote servers.
cap shell    #Begin an interactive Capistrano session.

Learn more about each with the explain switch(-e):
cap -e command #ie. cap -e deploy:pending:diff

Both of these are general-purpose, built-in tasks that allow you to run one or more commands on the deployment machines. The invoke task will run a single command, while shell opens up an irb-like command-prompt where you can issue multiple commands. But where are all the great things you can do with Capistrano?

In order to prepare your project for deployment, Capistrano provides us with the capify command, which builds the basic configuration files, and with a little bit of editing on our part our app will be ready to deploy. Taking my_project, previously configured as per Capistrano’s assumptions, we’ll create two files:

$ cd my_project
$ capify .
[add] writing `./Capfile'
[add] writing `./config/deploy.rb'
 [done] capified!

Now before we look at the two files created, let’s run cap --tasks again.

$ cap --tasks
cap deploy                #Deploys your project.
cap deploy:check          #Test deployment dependencies.
cap deploy:cleanup        #Clean up old releases.
cap deploy:cold           #Deploys and starts a 'cold' application.
cap deploy:migrate        #Run the migrate rake task.
cap deploy:migrations     #Deploy and run pending migrations.
cap deploy:pending        #Displays the commits since your last deploy.
cap deploy:pending:diff   #Displays the diff' since your last deploy.
cap deploy:restart        #Restarts your application.
cap deploy:rollback       #Rolls back to a previous version and restarts.
cap deploy:rollback_code  #Rolls back to the previously deployed version.
cap deploy:setup          #Prepares one or more servers for deployment.
cap deploy:start          #Start the application servers.
cap deploy:stop           #Stop the application servers.
cap deploy:symlink        #Updates the symlink to the deployed version.
cap deploy:update         #Copies your project and updates the symlink.
cap deploy:update_code    #Copies your project to the remote servers.
cap deploy:upload         #Copy files to the currently deployed version.
cap deploy:web:disable    #Present a maintenance page to visitors.
cap deploy:web:enable     #Makes the application web-accessible again.
cap invoke                #Invoke a single command on the remote servers.
cap shell                 #Begin an interactive Capistrano session.

Now that’s more like it! But where did these new tasks come from? For that answer, we’ll look at Capfile:

$ cat Capfile
require 'capistrano/version'
load 'deploy' if respond_to?(:namespace) # cap2 differentiator
load 'config/deploy'

It’s short! As you can see, the cap command loads up recipes by reading the Capfile in the present directory. Just like Rake, Capistrano will search up the directory tree until it finds a Capfile, which means you can run cap in a subdirectory of your project.

The Capfile built by capify loads up a bunch of standard Capistrano recipes in deploy, plus it also loads up your project-specific recipes in config/deploy:

my_project> $ cat config/deploy.rb

set :application, "set your application name here"
set :repository,  "set your repository location here"

# If you aren't deploying to /u/apps/#{application} on the target
# servers (which is the default), you can specify the actual location
# via the :deploy_to variable:
# set :deploy_to, "/var/www/#{application}"

# If you aren't using Subversion to manage your source code, specify
# your SCM below:
# set :scm, :subversion

role :app, "your app-server here"
role :web, "your web-server here"
role :db,  "your db-server here", :primary => true

Minor edits to the boilerplate config/deploy.rb file are all that’s required to prepare your app for deployment. The deploy.rb file describes your application deployment in simple-to-read language.

set :application, "set your application name here" # used as a folder
name

set :repository, "set your repository location here"

role :app, "my_deployment_machine" #or you can use an IP address
role :web, "my_deployment_machine"
role :db,  "my_deployment_machine", :primary => true

After a successful deploy, Capistrano is going to try to start (spin) your application. By default, it will look for ./script/spin, expecting that file to contain a script to start your application servers. It’s your job to write that script (since Rails doesn’t come with one), starting the app server of your choice. The easiest approach is to have your spin script talk to the spawner script, provided by Rails, since it knows how to fire up both FCGI and Mongrel.

You can read about the spawner tool easily; just type script/process/spawner --help at the console. A simple spin script to call spawner to start Mongrel^[5] will look like this:

/deploy_to/current/script/process/spawner -p 8256 -i 2

Add that line of code as ./script/spin to your repository, and upon a successful deploy, Capistrano will start two Mongrel instances, listening on ports 8256 and 8257. The distinct advantage of using the standard Rails spawner is that it will track the process ids, which means other standard Rails scripts are available. This includes script/reaper, used for restarting, monitoring, and stopping application server instances.

If you decide to step outside the tightly integrated spin solution, perhaps because you want to roll in some background process management, or you want to use a third-party startup script such as mongrel_cluster, then you’ll have to override the standard deploy tasks. Later on in the chapter, in Baking Exercise #2, we’ll show you how to do just that.

Now that we’ve got our default configuration in place, and all assumptions are covered, we can ask Capistrano to set up our deployment machine. What does setup mean? The deploy:setup task essentially creates the directory structure that holds your application deployments.

$ cap deploy:setup

releases
current
shared
shared/log
shared/system
shared/pids

cap --quiet deploy:check # quiet shuts out the verbosity

depend :remote, :gem, "runt", ">= 0.3.0"
depend :remote, :directory, :writeable, /var/www/current/config
depend :remote, :command, "monit"
depend :local, :command, "svn"

The following dependencies failed. Please check them and try again:
--> gem `runt' >= 0.3.0 could not be found (my_deployment_machine)

If you’ve done everything correctly up to now in setting up your application’s deploy.rb script and you have set up the remote machines, then you’re ready to actually do a deployment.

On a first deploy of this app, we’ll run cap deploy:cold —otherwise we’d run the default task cap deploy. The only difference between these two is that cap deploy will try to shut down your server first, which won’t work since it isn’t running yet.

$ cap deploy:cold # cold will "svn co", run migrations, link this
release
                  # to the current and start your servers

In most cases, you will be asked to enter the password to your svn server. This is a case where it is extremely handy to have set up SSH keys on the local and client machine so that you authenticate automatically with certificates instead of having to enter passwords multiple times.

If all went well, you shouldn’t see any error messages, and a browser session will show your app is up. If not, read the verbose output, go over the assumptions, and start again.

To use a remote user account other than the currently logged-in user, just set the :user variable to the desired remote user account name.

set :user, "deploy"

That was simple, and also makes an important point. Capistrano tries to simplify working outside the stated assumptions. Another example would be changing the source-control system to something other than Subversion.

Although the default SCM system is Subversion, Perforce, Bzr, and Darcs are also supported.

set :scm, :subversion # default. :perforce, :bzr, :darcs

You can also customize the deployment strategy, and we do not recommend that you stick with the default, which is :checkout, since it is very inefficient. All those little .svn directories chew up disk space like crazy! Instead, try the :export option, which will do an svn export of your codebase into the release directory. The :remote_cache performs well also, since it makes a copy of the last release, and then executes svn up to get the latest code, but we like :export best.

set :deploy_via, :checkout         # default
set :deploy_via, :export
set :deploy_via, :remote_cache # copies from cache, then svn up

Sometimes, particularly for security reasons, you don’t have (or want) access to SCM on your deployment machine. For these cases, Capistrano provides a means to deploy_via :copy. The :copy strategy tars and gzips your project before using SFTP to upload it to the release directory on the remote machine. In the rare case that your local machine does not have the required binaries, you can tell Capistrano to use Ruby’s internal zip library.

set :deploy_via, :copy        # local scm check out.
                    # Cap will tar/gzip sftp to deployment machine

set :copy_strategy, :export  # changes deploy_via :copy to :export
                    # instead of default scm check out

set :copy_compression, :zip    # if you don't have tar/gzip binaries,
                    # Cap will zip for you

Hopefully you are noticing that although Capistrano’s assumptions are good defaults, you have a great deal of flexibility in specifying alternatives, without having to write your own tasks.

People sometimes leave configuration files such as database.yml out of the repository for a number of reasons, among them security concerns. We don’t advise this practice, since it complicates distributed development and local config requirements. However, learning how to work around the challenge posed by nonversioned configuration files provides us a valuable and realistic opportunity to teach you how to move beyond basic understanding of Capistrano.

Note that out of the following three options, there is only one that is really good in our opinion. However, you stand to learn from all three.

task :after_update_code, :roles => :app do
  run "cp #{release_path}/config/production.database.yml
          #{release_path}/config/database.yml"
end

task :after_symlink, :roles => :app do
   run "cp #{shared_path}/config/database.yml
           #{release_path}/config/database.yml"
end

then...
 a. cap setup
 b. copy production-ready database.yml file to the shared/config
folder
 c. cap cold_deploy

require 'erb'

before "deploy:setup", :db
after "deploy:update_code", "db:symlink"

namespace :db do
  desc "Create database yaml in shared path"
  task :default do
    db_config = ERB.new <<-EOF
    base: &base
      adapter: mysql
      socket: /tmp/mysql.sock
      username: #{user}
      password: #{password}

    development:
      database: #{application}_dev
      <<: *base

    test:
      database: #{application}_test
      <<: *base

    production:
      database: #{application}_prod
      <<: *base
    EOF

    run "mkdir -p #{shared_path}/config"
    put db_config.result, "#{shared_path}/config/database.yml"
  end

  desc "Make symlink for database yaml"
  task :symlink do
    run "ln -nfs #{shared_path}/config/database.yml
         #{release_path}/config/database.yml"
  end
end

$ cap deploy:setup
$ cap deploy:update

The Capistrano recipe deploy:migrations expects a database.yml production-specified database, does a deployment as usual, and runs any pending migrations. Unfortunately, it is pretty common to get yourself into a situation where your whole suite of migrations won’t run without an error.

One possible solution is to create a task that sets up your database using db/schema.rb, a Ruby script that (using the Migrations API) handily stores the most recently migrated version of your database schema (DDL). The Capistrano task in Listing 21.3 loads the schema.

namespace :deploy do
  desc "runs 'rake db:schema:load' for current release"
  task :load_schema, :roles => :db do

    rake = fetch(:rake, "rake")
    rails_env = fetch(:rails_env, "production")

    run "cd #{current_release}; #{rake} RAILS_ENV=#{rails_env}
db:schema:load"
  end
end

Run the task in two steps: cap deploy:cold followed by cap deploy:load_schema.

There are two ways we can specify variables. One is from the recipe definitions (as we’ve already seen in this chapter). The other is from the command line.

From the command line we can set variable values using either an -s or -S switch. Typing cap -s foo=bar is equivalent to having set :foo, "bar" after all your recipes are loaded, and cap -S foo=bar does so before recipes are loaded.

As with Rake, you can also specify variables within the OS environment. As this is a little tougher in Windows, Capistrano command-line switches are a better cross-platform solution.

Whenever possible, I prefer to create specific Capistrano tasks that set common variables rather than depend on shell scripts or command-line operations. This keeps the deployment knowledge within Capistrano, and not spread around your environment.

A topic that deserves a little investigation at this time is the scoping of Capistrano variables. Are variables local to the task? Local to the namespace? Or global to Capistrano in general? To figure out this bit of undocumented Capistrano, we’re going to write some tasks (Listing 21.4) to play with the possibilities. We’ll start by creating two namespaces (:one and :two) and assign identically named variables (:var_one) to them. Then we’ll set and get those values from a third namespace. The resulting values should teach us much about Capistrano’s scoping rules.

namespace :one do
  task :default do
    set :var_one, "var_one value"
  end
end

namespace :two do
  task :default do
    set :var_one, "var_two value"
  end
end

namespace :three do
  task :default do
    puts "!!!! one.var_one == #{one.var_one}"
    puts "!!!! global name space var_one == #{var_one}"

    two.default

    puts "!!!! one.var_one == #{one.var_one}"
    puts "!!!! two.var_one == #{two.var_one}"
    puts "!!!! global name space var_one == #{var_one}"
  end
end

before "deploy:update", :one
before "deploy:update", :two
after "deploy:update", :three

$cap deploy:update

Running the code in Listing 21.4 dumps the following output to the console:

  * executing `three' # run one
!!!! one.var_one == var_one value
!!!! global name space var_one == var_one value

  * executing `two' # run two
!!!! one.var_one == var_two value
!!!! two.var_one == var_two value
!!!! global name space var_one == var_two value

What does this mean? First we can see that referencing one.var_one and (the global) var_one returns the same value; looks as if they’re one and the same. Taking a second kick at it, in the second run we call task two.default. Setting only two.var_one confirms that there isn’t a local variable namespace—but simply one global namespace for variables.

In the preceding tester code you may have noticed the funny two.default call in the example—this is simply the way to call namespaced tasks. In the case of default, we use the explicit name (merely two won’t resolve as it does in the namespace syntax shortcut :two).

In summary, we have shown that variables aren’t scoped by namespace; referencing them by namespace will always return the global value and will probably confuse you and others down the line. But be aware that scoped variables are planned for a future version of Capistrano.

A particularly useful trick with Capistrano is the ability to initialize a starting configuration for tasks. A great use for such preinitialization is for setting up the environment for which we will be deploying.

We can do this in two ways; first, using the -S switch to set an initial value:

$ cap -S app_server=the_rails_way.com,secure_ssh_port=8256 deploy

The deploy task will be run with the app_server and secure_ssh_port parameters set. This strategy rapidly gets out of hand as we need new parameters. Do we need an additional shell script to hold those parameters? Yuck! Capistrano can be a powerful friend, especially if you don’t distribute your deployment logic.

The second, and much more DRY, method is to code tasks that define each of your staging environments, so that you can say something like cap production deploy, letting the production task setup the needed variables, just as we show you in Listing 21.5.

desc "deploy to the production environment"
task :production do
   set :tag, "release-1.0" unless variables[:tag]
   set :domain, "the-rails-way.com"
   set :repository, "http://svn.nnovation.ca/svn/the-rails-
way/tags/#{tag}"
   set :rails_env, "production"
   set :app_server, "the-rails-way.net"
   set :secure_ssh_port, 8256

   role :app, "#{app_server}:#{secure_ssh_port}"
   role :web, "#{app_server}:#{secure_ssh_port}"
   role :db,  "#{app_server}:#{secure_ssh_port}", :primary => true
end

desc "deploy to the staging environment"
task :staging do
  set :domain, "staging.the-rails-way.com"
  set :repository, "http://svn.nnovation.ca/svn/the-rails-way/trunk"
  set :rails_env, "development"
  set :app_server, "staging.the-rails-way.com"
  set :secure_ssh_port, 8256

  role :app, "#{app_server}:#{secure_ssh_port}"
  role :web, "#{app_server}:#{secure_ssh_port}"
  role :db,  "#{app_server}:#{secure_ssh_port}", :primary => true
end

Thus, we can deploy very concisely and without worrying about command-line parameters.

$ cap staging deploy    # trunk to staging
$ cap production deploy # tags/release-1.0 to production

Now I don’t know about you, but those repetitive role assignments smell a little. How about we just move them out of the tasks, perhaps below the two task definitions? We tried, and learned an important lesson when Capistrano reported that app_server and secure_ssh_port weren’t understood. Is it a matter of scoping? Is our execution order off?

The answer is that both scoping and execution order are coming into play. When you move the role assignments out of the task’s do..end blocks into the main body of the script, you are changing the timing of their evaluation. Those lines will in fact execute prior to the code that is inside of the task definition. So in this particular case, the role assignments would get executed before an app_server value is set.

Luckily for us, the solution is pretty simple and simplifies our code nicely. We’ll do a Capistrano version of an extract method refactoring, except with an additional task instead of a method.

Define a task named :finalize_staging_init, and then add a call to it at the end of the staging and production tasks.

task :staging do
  set :domain, "staging.the-rails-way.com"
  set :repository, "http://svn.nnovation.ca/svn/the-rails-way/trunk"
  set :rails_env, "development"
  set :app_server, "staging.the-rails-way.com"
  set :secure_ssh_port, 8256

  finalize_staging_init
end

task :production do
  set :tag, "release-1.0" unless variables[:tag]
  set :domain, "the-rails-way.com"
  set :repository, "http://svn.nnovation.ca/svn/the-rails-
way/tags/#{tag}"
  set :rails_env, "production"
  set :app_server, "the-rails-way.net"
  set :secure_ssh_port, 8256

 finalize_staging_init
end

task :finalize_staging_init do
  role :app, "#{app_server}:#{secure_ssh_port}"
  role :web, "#{app_server}:#{secure_ssh_port}"
  role :db,  "#{app_server}:#{secure_ssh_port}", :primary => true
end

A typical Rails deployment scenario involves a cluster of Mongrels, and perhaps some additional processes such as backgroundrb, memcache, and search engine daemons.

The canned deploy:start, :stop, and :start take care of a single Mongrel instance fronted by Apache. In this exercise, as shown in Listing 21.6, we’re going to override the default tasks, and insert our own to manage a Mongrel cluster and a BackgrounDRb installation; however, note that this recipe doesn’t manage Apache, as I rarely bring it up or down. At this point you should know enough about Capistrano to understand the recipe and easily bake in Apache support.

namespace :deploy do

  desc "Restart the Mongrel cluster and backgroundrb"
  task :restart, :roles => :app do
    stop
    start
  end

  desc "Start the mongrel cluster and backgroundrb"
  task :start, :roles => :app do
    start_mongrel
    start_backgroundrb
  end

  desc "Stop the mongrel cluster and backgroundrb"
  task :stop, :roles => :app do
    stop_mongrel
    stop_backgroundrb
  end

  desc "Start Mongrel"
  task :start_mongrel, :roles => :app do
    begin
      run "mongrel_cluster_ctl start -c #{app_mongrel_config_dir}"
    rescue RuntimeError => e
      puts e
      puts "Mongrel appears to be down already. "
    end
  end

  desc "Stop Mongrel"
  task :stop_mongrel, :roles => :app do
    begin
      run "mongrel_cluster_ctl stop -c #{app_mongrel_config_dir}"
    rescue RuntimeError => e
      puts e
      puts "Mongrel appears to be down already. "
    end
  end

  desc "Start the backgroundrb server"
  task :start_backgroundrb , :roles => :app do
    begin
      puts "starting brb in folder #{current_path}"
      run "cd #{current_path} && RAILS_ENV=#{rails_env} nohup
./script/backgroundrb start > /dev/null 2>&1"
    rescue RuntimeError => e
      puts e
      puts "Problems starting backgroundrb - running already?"
    end
  end

  desc "Stop the backgroundrb server"
  task :stop_backgroundrb , :roles => :app do
    begin
      puts "stopping brb in folder #{current_path}"
      run "cd #{current_path} && ./script/backgroundrb stop"
    rescue RuntimeError => e
      puts e
      puts "Backgroundrb appears to be down already."
    end
  end
end