Deploying with Capistrano and mongrel_cluster

Problem

You want to use Capistrano to deploy a web application that's being served by several Mongrel processes. You need the ability to stop and start your entire Mongrel cluster with one command; bringing a half-dozen servers up and down manually is driving you crazy!

Solution

If your Rails application is being served by more the one Mongrel server, and you don't have mongrel_cluster installed, install it now. In addition to making it easier to start and stop all of your Mongrel processes with one mongrel_rails command, the mongrel_cluster gem includes a custom Capistrano task that overrides the default tasks that were initially designed for use with Apache and FastCGI.

Installing the mongrel_cluster gem gives you a library of Capistrano tasks that you can include in your deployment environment. Once you've installed mongrel_cluster, look for a file called recipes.rb located under the mongrel_cluster gem directory. (On Unix-based systems, this should be /usr/local/lib/ruby/gems/1.8/gems/.) Within that directory, the name of the mongrel_cluster gem should be something like mongrel_cluster-0.2.0/lib/mongrel_cluster (depending on the version of the gem).

First, apply Capistrano to your application, if you haven't done so already: 

$ cap --apply-to /var/www/cookbook

Then, make the task library included with mongrel_cluster available to the cap command within the context of your application. To do this, include the following require statement at the top of you application's deploy.rb:

config/deploy.rb: 

 require 'mongrel_cluster/recipes'
set :application, "cookbook"
set :repository, "https://orsini.us/svn/#{application}"
role :web, "tupleshop.com"
role :app, "tupleshop.com"
set :user, "rob"
set :deploy_to, "/var/www/apps/#{application}"

Also, you should have a mongrel_cluster configuration file that contains something like the following:

config/mongrel_cluster.yml: 

--- 
cwd: /var/www/cookbook/current port: "8000"
environment: production pid_file: log/mongrel.pid servers: 2

Initialize your application on the servers with: 

$ cap setup

On the server (or servers) create a directory in /etc called mongrel_cluster. Within that directory, create a symbolic link to your application's mongrel_cluster.yml. 

$ sudo mkdir /etc/mongrel_cluster
$ cd /etc/mongrel_cluster
$ ln -s /var/www/apps/cookbook/current/config/mongrel_cluster.yml 
 cookbook.conf

The symbolic link is named after the application that it applies to. Now, deploy your project with: 

$ cap deploy

Capistrano performs the standard sequence of deployment events: checking out the latest version of your project from your Subversion repository and updating the "current" symbolic link to point to the new version of your application on the server. Finally, Capistrano restarts your mongrel_cluster with the following two commands: 

sudo mongrel_rails cluster::stop -C /etc/mongrel_cluster/cookbook.conf sudo mongrel_rails cluster::start -C /etc/mongrel_cluster/cookbook.conf

Discussion

The following are all the of the Mongrel-related tasks that the mongrel_cluster adds to your Capistrano deployment environment:


configure_mongrel_cluster

Configure Mongrel processes on the application server. This task uses the :use_sudo variable to determine whether to use sudo or not. By default, :use_sudo is set to TRue.


spinner

Start the Mongrel processes on the application server by calling restart_mongrel_cluster.


restart

Restart the Mongrel processes on the application server by calling restart_mongrel_cluster.


restart_mongrel_cluster

Restart the Mongrel processes on the application server by starting and stopping the cluster.


start_mongrel_cluster

Start Mongrel processes on the application server.


stop_mongrel_cluster

Stop the Mongrel processes on the application server.

The fact that Capistrano ships with the assumption that you're running Apache with FastCGI probably dates it a bit. This isn't really a big deal because of the ease with which you can customize, override, and create your own tasks.

See Also