VlCapistrano is being replaced with VigetDeployment?. The following is for historical purposes and/or projects still using the older code.

VL Capistrano

VL Capistrano provides a new deployment strategy and several useful convenience methods for Capistrano 2.0.

This version of VL Capistrano is not compatible with Capistrano 1.4.1 or earlier.

Gem preliminaries

Obviously, VL Capistrano depends on Capistrano. The version of number of VL Capistrano is either x.y.z or x.y.z.w, where x.y.z equals a targeted version of Capistrano; thus VL Capistrano 2.0.0.1 is targeted to Capistrano 2.0.0. Capistrano can be installed with the usual gem install capistrano -y

Starting with VL Capistrano 2.0.0.1, the deployment strategy is provided as a separate gem, CapistranoRsyncWithRemoteCache, on which VL Capistrano depends.

Starting with VL Capistrano 2.0.0.2, the Campfire notifier is provided as a separate gem, CapistranoCampfireNotifier, on which VL Capistrano depends.

To create the gem, run rake package in this directory, which will dump the gem in the pkg subdirectory.

To use the tasks included with the gem, add these lines to Capfile:

require 'capistrano/recipes/viget'

set :rails_env, 'production'

:rails_env defines the default Rails environment which will be operated on by Capistrano. This can be overridden by passing RAILS_ENV on the command line. You may want a different default, such as 'stage'.

rsync deployment with remote cache

To use the Capistrano::Deploy::Strategy::RsyncWithRemoteCache method, add this line to Capfile:

set :deploy_via, :rsync_with_remote_cache

More documentation is provided with the capistrano_rsync_with_remote_cache gem.

Mongrel cluster operation

This gem overrides the standard deploy:start, deploy:restart and deploy:stop tasks to use mongrel_cluster.

New deploy options

This gem also enables some custom options that can be used in the Capfile.

symlinks - defines an array of paths that will be symlinked after the code is updated. For instance:

set :symlinks, ['public/images/uploaded']

would create a link on the server from shared/public/images/uploaded to current/public/images/uploaded.

timezone - specifies the time zone in which the application should run. It could be one of the following:

  • EST5EDT for US Eastern time
  • CST6CDT for US Central time
  • MST7MDT for US Mountain time
  • PST8PDT for US Pacific time
  • UTC for UTC

If not specified, this defaults to the timezone set on the server, which is often but not always UTC.

Lockouts

Lockouts are files named LOCKOUT.environment (for any value of environment) in the Rails root which will cause the update_code task for the given environment to abort and show their contents. This is intended to deliberately prevent deploying broken or inappropriate code.

To create a lockout, use the "vl:lockout:add" task:

RAILS_ENV=production REASON="it's broken" cap vl:lockout:add

This will create a lockout with your login and the reason for the lockout, and commit it to Subversion. RAILS_ENV specifies the environment to lock out; the default is default_env in the configuration. To remove it when everything is fixed, use the "vl:lockout:remove" task (REASON does not need to be specified when removing a lockout.)

The LOCKOUT.environment file can also be edited by hand; it is just a plain text file. However, using the cap tasks is recommended.

Database Dumps and Restores

To dump the database on the remote server, use the "vl:db:dump" task:

RAILS_ENV=production cap vl:db:dump

When capistrano/recipes/viget is required, this task will be run automatically before each deployment.

To restore the database from the dump (if any), use the "vl:db:restore" task similarly to vl:db:dump. FIXME: this doesn't happen yet: When capistrano/recipes/viget is required, this task will be run automatically if the update_code task rolls back.

Custom Maintenance Pages

The deploy:web:disable task has been extended to support a custom maintenance page. See http://clarkware.com/cgi/blosxom/2007/01/05#CustomMaintenancePages for an example of how this works. The custom maintenance page layout, if any, should be placed in app/views/layouts/maintenance.erb (not maintenance.rhtml as in Mike's article.)

Campfire Notifications

NOTE: The Campfire configuration has changed since the release of VL Capistrano 2.0.

VL Capistrano can notify one or more Campfire rooms upon a successful deployment. To enable this feature, set the :campfires variable to a hash such as the following: 

set :campfires, { 'Viget' => {:domain => 'vl', :room => 'Roomname', :email => 'me@example.com', :password => 'password'},
                  'Client' => {:domain => 'client', :room => 'Roomname', :email => 'you@example.com', :password => 'drowssap'} }

Then set :campfire_notify to an array of keys from that hash, specifying the rooms to notify:

set :campfire_notify, ['Viget','Client']

It's recommended to set :campfires in your $HOME/.caprc file instead of in a Capfile. This lets you check your Capfile into version control without exposing sensitive login credentials. The :campfire_notify variable lets you keep all of your Campfire info for all of your projects in one file, while only selecting the Campfires appropriate for a given project.

For Those Who Used VL Capistrano 0.x-1.x

The names of the custom tasks have changed.

  • lockout is now vl:lockout:add
  • remove_lockout is now vl:lockout:remove
  • dump_db is now vl:db:dump
  • setup_rsync_caches no longer exists (caches are set up automatically)

Future Work

The multiple environment support (i.e. RAILS_ENV) will likely be changed to support the multistage method from the capistrano-ext gem: http://weblog.jamisbuck.org/2007/7/23/capistrano-multistage Ideally this will be done in a way that is backwards compatible with the current method.