Capistrano

From NHRubyWiki

This page is an overview and cheat-sheet for Capistrano, a tool for deploying Ruby on Rails applications. Please note it is NOT a complete tutorial for deploying Rails applications; for that you should read the excellent deployment chapter from the book Agile Web Development with Rails, 2nd Edition, or various on-line tutorials.

Contents 1 Configure Mongrel Cluster 2 Installing Capistrano 3 Setup Capistrano 4 Configure deploy.rb 5 First Deployment 6 Capistrano Commands

Configure Mongrel Cluster

First, if you're deploying with a pack of mongrels, create a mongrel cluster configuration file with the mongrel_rails command:

mongrel_rails cluster::configure -e production -p 8000 \
    -a 127.0.0.1 -N 3 -c /<deployment_path>/current \
    --user <deployment_user> --group <deployment_group>

This will generate a mongrel_cluster.yml file in your config/ directory. It configures the mongrel cluster to have three instances (-N 3) which run on port 8000, 8001, and 8002, in the specified deployment directory on your production server. It also runs mongrel as the specified user and group; it's important for security reasons that you don't run it as root.

Installing Capistrano

You'll need to install the following gems on your deployment server: rails mongrel mongrel_cluster termios.

You'll need to install the following gems on your development machine (the one which issues deployment commands): rails mongrel mongrel_cluster termios capistrano.

Setup Capistrano

Generate the necessary capistrano configuration file (deploy.rb) by cd'ing into your rails project directory and running:

cap --apply-to . <app_name>

<app_name> is just a string to identify this application - it's usually named after the rails project name.

Note: As of capistrano v1.4.1, a deprecated file lib/tasks/capistrano.rake is created. It is OK to delete this file if you don't want it lying around unused.

Configure deploy.rb

You will want to make the following changes to your deploy.rb file:

• Add require 'mongrel_cluster/recipes' to the top of the file (for mongrel cluster support).
•  :repository should be edited to reflect your source code repository URI.
•  :deploy_to should be edited to reflect the filesystem path you're deploying to on your deployment server.
•  :web, :app, and :db should be edited to reflect which servers are your web, application, and database servers (for single-server setups these will all point to the same server).
• Add :mongrel_conf and point it to where you store your mongrel_cluster.yml file for this project (typically "#{current_path}/config/mongrel_cluster.yml").
• If you're using subversion, add the following line: set :checkout, :export to avoid a security vulnerability which can occur when doing subversion checkouts.

Look through the remaining configuration options and modify them if needed.

First Deployment

Before performing your first deployment, run the following command to create capistrano's deployment directory structure on the deployment server:

cap setup

Now, you should be able to issue your first deployment:

cap cold_deploy

From then on, you can use one of the commands listed below for deployments and other server-side recipes.

Capistrano Commands

cap show_tasks

Displays all available capistrano tasks you can run.