Deploying ColdFusion Apps With Capistrano Part 2

In my last post, I covered the basics of what we are trying to accomplish and some basic requirements and setup. Hopefully by now, even you Windows users have Ruby installed and the needed gems, because the fun stuff is about to begin.

The project Im deploying uses Git for SCM and lives on GitHub so Im going to focus on that as the repository to pull releases from. You can just as easily use SVN if you want with a minor tweak to your Capistrano deploy config.

Configuring Your Site

This is where all the configuration happens. Although for a basic deployment, there isnt alot of configuration. First off, you have to create your config files. Fortunately, Capistrano will do that for us. Change directory into the root or your application and type:

$ capify .

This will create a directory and two files, /Capfile, /config/, and /config/deploy.rb. These are really the only config files needed for deployment but we have to tweak them a bit since we arent using Rails.
Open up Capfile in your favorite text editor and replace its contents with the following:

require 'rubygems'
require 'railsless-deploy'
load 'config/deploy' if respond_to?(:namespace)

This basically just tells Capistrano to use the railsless-deploy gem that we installed earlier for deployments as well as tell it where our deploy.rb (recipe) is located. Its common for the /config/deploy.rb file to be referred to as a recipe so those will be used interchangeably.

Next, open the config/deploy.rb file and set it up like this example:

#replace with your servers information
set :domain, ""
set :user, "sshuser"

# this name should be the same as the deployment directory on the server
set :application, "site"

set :scm, :git
set :branch, "master"

# specify a hosted repository
set :repository,  ""

# or you can use the path to your local repository
#set :repository,  "file://#{File.expand_path('.')}"

server "#{domain}", :app, :web, :db, :primary => true

set :deploy_via, :copy
set :copy_exclude, [".git", ".DS_Store"]

# set this to the deployment path on your server
set :deploy_to, "/home/#{user}/public_html/#{application}"

set :keep_releases, 3
set :git_shallow_clone, 1

ssh_options[:paranoid] = false
ssh_options[:forward_agent] = true
set :use_sudo, false

# this tells capistrano what to do when you deploy
namespace :deploy do

  desc <<-DESC
  A macro-task that updates the code and fixes the symlink.
  task :default do
    transaction do

  task :update_code, :except => { :no_release => true } do
    on_rollback { run "rm -rf #{release_path}; true" }

  task :after_deploy do

As you can see, there are several options available for deployment and you can alter the recipe to use SVN if you need, etc. The Capistrano wiki has some great documentation on all of the options available to you.

Server Setup

Now that you have your application ready to deploy, we need to tackle a couple small tasks on the server to get it ready to have our app deployed to it. Again, Im deploying to an Ubuntu server so I will be showing you the commandline way of doing it.

SSH onto your server and make sure that the deployment path that you set in your recipe exists:

$ mkdir /home/user/public_html/site

Now, on your workstation, you can allow Capistrano to setup the directory structure it uses for deployments. While still in the root directory of your site, simply type:

$ cap deploy:setup

Capistrano will go to work on your server for you and run several tasks. Primarily what you should take note of is the directory structure it creates for you. It will look like this:


What this does is allows Capistrano to keep the number of releases you specified in your recipe in the releases directory so you can easily roll them back if need be. The shared directory is used for holding files that do not change from deployments such as uploaded images or config files. I use it to store my environment.cfm config for my CFWheels applications so when I deploy, it always points to the production environment.

Once that is done, your ready to deploy your application. On your workstation, type the following command:

$ cap deploy

This will grab the latest copy of your application from your SCM repository and deploy it to the releases directory. The other thing it does is create a symlink on your server called current/. This symlink is recreated each time you deploy your site to point to the latest released copy under the releases directory.

You have one more task on the server that has to be done in order for this to all come together. If your website root path is pointing to /home/user/public_html or something similar, you will need to repoint this to your current symlink, /home/user/public_html/site/current. This sets the doc root for your application and your site should be up and running.

After making some changes to your site and your ready to deploy the latest version, simply type cap deploy in your site root again and Capistrano will create a new folder under releases and push the latest code there. Then it recreates the current symlink and your site will be up and running the latest version. How simple is that?

Somethings Wrong, I Need to Rollback!

So in your last release you found a problem in your application, no problem. You can instantly rollback your server to the previous version by simply typing the following command on your workstation inside your applications root folder:

$ cap deploy:rollback

This will completely remove the failed last release and repoint the symlink to the previous release.

Whats Next?

If your running a simple web app or site, this should probably suffice for most of your needs. But for something that involves a little more configuration, etc. I will be doing a 3rd part to this post soon that will cover creating additional deployment tasks in your recipe to handle things like creating symlinks to shared config files, cleanup tasks and all sorts of goodies.

Stay tuned…

3 thoughts on “Deploying ColdFusion Apps With Capistrano Part 2”

  1. In your experience, have you had any issues with coldfusion not being able to find files after a cap deploy? Restarting colfusion seems to fix my issue, but that’s not very optimal. I’m running CF 9 are you also running CF 9 or are you running CF 8?

Leave a Reply

Your email address will not be published. Required fields are marked *