cool tech graphics

Capistrano: Drupal deployments made easy, Part 1

Filed under:

I'm a big fan of having an automated deployment process. It's really the web development analog to the "one step build process", as described in the Joel Test. In the past I have used various shell scripts to perform this task, but I have recently become a convert to Capistrano (or "cap" for short). With Capistrano, uploading your code to the test server is as simple as typing cap deploy. When you're ready to launch in production, it's just cap production deploy.


Simply put, Capistrano is a tool for automating tasks on one or more remote servers. It executes commands in parallel on all targeted machines, and provides a mechanism for rolling back changes across multiple machines.

In detail, here are the features that got me hooked. There's a lot more that cap can do, and I'll describe some more tricks in part 2 of this post.

  • Atomic deployments with error checking. Cap uses a set of symlinked directories, and the links are updated during the final step. It also won't allow a deployment to keep plowing ahead if an intermediate step fails. This makes your deployment atomic; it will either fail or succeed entirely.
  • Fast rollback. If something does go wrong, getting back to the previous state is as simple as cap deploy:rollback.
  • Parallel execution. If you use multiple servers in a load-balanced environment, cap can make managing them easier.
  • Multistage deployments. "Stages" are different server instances of your code. You may have different servers for development, content entry, and production. With the Multistage extension, cap can share code for common tasks between these stages.


First, you'll need to install Capistrano, as well as the multistage extensions contained in capistrano-ext:

gem install capistrano
gem install capistrano-ext

Next, you'll need to add a couple of files to your project (the files' contents are listed at the end of this post). I lay out projects like this:

|-- capfile
|-- config
|   |-- deploy
|   |   |-- development.rb
|   |   `-- production.rb
|   `-- deploy.rb
`-- drupal
    `-- index.php

Now edit the paths and project name in config/deploy.rb and config/deploy/development.rb to suit your environment.

You're now ready to run cap deploy:setup. This task only needs to be run once, prior to the first deployment. It will create the necessary directories on your server, which will ultimately look something like the tree below. (Until your first deployment, there may not be anything in the releases directory, nor a link from current). Also notice the setup task created a local_settings.php file. The utility of this is described in my post on stage-specific settings. The web server document root in this example is /var/www/current.

|-- current -> /var/www/releases/20091023202918
|-- releases
|   |-- 20091023191450
|   `-- 20091023202918
`-- shared
    |-- cached-copy
    |-- default
    |   |-- files
    |   `-- local_settings.php
    `-- system

Finally, run cap deploy.

cap deploy will speedily upload a new release of your project, then link it to the current document root if all went well.

Watch for part 2, where I'll cover some extra tasks included in this Capfile, as well as managing multi-site and multi-stage deployments.


### This file contains project-specific settings ###
# The project name.
set :application, "myproject"
# List the Drupal multi-site folders.  Use "default" if no multi-sites are installed.
set :domains, ["default"]
# Set the repository type and location to deploy from.
set :scm, :subversion
set :repository,  ""
# Use a remote cache to speed things up
set :deploy_via, :remote_cache
# Multistage support - see config/deploy/[STAGE].rb for specific configs
set :default_stage, "development"
set :stages, %w(production development)
# Generally don't need sudo for this deploy setup
set :use_sudo, false


### This file contains stage-specific settings ###
# Set the deployment directory on the target hosts.
set :deploy_to, "/var/www/#{application}"
# The hostnames to deploy to.
role :web, ""
# Specify one of the web servers to use for database backups or updates.
# This server should also be running Drupal.
role :db, "", :primary => true
# The username on the target system, if different from your local username
# ssh_options[:user] = 'alice'
# The path to drush
set :drush, "cd #{current_path} ; /usr/bin/php /data/lib/php/drush/drush.php"


This file does the real work. If you aren't a ruby programmer, don't panic; neither am I (yet). Hopefully, this is general-purpose enough that it will work for you out of the box. Additionally, individual tasks can be overridden in deploy.rb or development.rb – so once you have a Capfile you like the same file can be reused across all your projects.

load 'deploy' if respond_to?(:namespace) # cap2 differentiator
Dir['vendor/plugins/*/recipes/*.rb'].each { |plugin| load(plugin) }
load 'config/deploy.rb'
require 'capistrano/ext/multistage'
namespace :deploy do
  # Overwritten to provide flexibility for people who aren't using Rails.
  desc "Prepares one or more servers for deployment."
  task :setup, :except => { :no_release => true } do
    dirs = [deploy_to, releases_path, shared_path]
    domains.each do |domain|
      dirs += [shared_path + "/#{domain}/files"]
    dirs += %w(system).map { |d| File.join(shared_path, d) }
    run "umask 02 && mkdir -p #{dirs.join(' ')}" 
  desc "Create settings.php in shared/config" 
  task :after_setup do
    configuration = <<-EOF
$db_url = 'mysql://username:password@localhost/databasename';
$db_prefix = '';
    domains.each do |domain|
      put configuration, "#{deploy_to}/#{shared_dir}/#{domain}/local_settings.php"
  desc "link file dirs" 
  task :after_update_code do
    domains.each do |domain|
    # link settings file
      run "ln -nfs #{deploy_to}/#{shared_dir}/#{domain}/local_settings.php #{release_path}/sites/#{domain}/local_settings.php"
      # remove any link or directory that was exported from SCM, and link to remote Drupal filesystem
      run "rm -rf #{release_path}/sites/#{domain}/files"
      run "ln -nfs #{deploy_to}/#{shared_dir}/#{domain}/files #{release_path}/sites/#{domain}/files"
  # desc '[internal] Touches up the released code.'
  task :finalize_update, :except => { :no_release => true } do
    run "chmod -R g+w #{release_path}"
  desc "Flush the Drupal cache system."
  task :cacheclear, :roles => :db, :only => { :primary => true } do
    domains.each do |domain|
      run "#{drush} --uri=#{domain} cache clear"
  namespace :web do
    desc "Set Drupal maintainance mode to online."
    task :enable do
      domains.each do |domain|
        php = 'variable_set("site_offline", FALSE)'
        run "#{drush} --uri=#{domain} eval '#{php}'"
    desc "Set Drupal maintainance mode to off-line."
    task :disable do
      domains.each do |domain|
        php = 'variable_set("site_offline", TRUE)'
        run "#{drush} --uri=#{domain} eval '#{php}'"
  after "deploy", "deploy:cacheclear"
  after "deploy", "deploy:cleanup"
  # Each of the following tasks are Rails specific. They're removed.
  task :migrate do
  task :migrations do
  task :cold do
  task :start do
  task :stop do
  task :restart do
desc "Download a backup of the database(s) from the given stage."
task :download_db, :roles => :db, :only => { :primary => true } do
  domains.each do |domain|
    filename = "#{domain}_#{stage}.sql"
    run "#{drush} --uri=#{domain} sql dump --structure-tables-key=common > ~/#{filename}"
    download("~/#{filename}", "db/#{filename}", :via=> :scp)
Date posted: November 6, 2009


We used Capistrano on a large project not too long ago and while we it was mostly a good experience, it was also very frustrating at times. Running gem install or update took forever, Capistrano required specific versions of certain ruby gems and it had pretty much no Wndows support at the time. Since then we've had much better luck with our own bash scripts and haven't looked back.

I can thoroughly recommend my railsless-deploy gem (see github, or - it removes all of the railsisms so you don't need to stub out all the rails default methods; should make your output cleaner, and marginally quicker deploys

Lee, Thanks for pointing that out! That sounds like a great tool. That also makes me think that someday a Drupal "personality" for Cap could live on gemcutter, further shrinking or eliminating many of the standard task definitions.

I just finished my own capistrano recipe pour deploying Drupal websites. It's not complete yet but it should work with setup/deploy and rollback tasks :

I only tested this with Mercurial and inside webistrano. Feedback welcome.

thanks. i havent had time to look into deployment yet, but someone posted your article on irc. now i am curious. thanks for that good starting point.

Add new comment

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • You can enable syntax highlighting of source code with the following tags: <code>, <blockcode>, <cpp>, <java>, <php>. The supported tag styles are: <foo>, [foo].
  • Web page addresses and email addresses turn into links automatically.
  • Lines and paragraphs break automatically.

Metal Toad is an Advanced AWS Consulting Partner. Learn more about our AWS Managed Services

Schedule a Free Consultation

Speak with our team to understand how Metal Toad can help you drive innovation, growth, and success.