Anatomy of a capistrano installation

Typically inside your application you will have a structure not dissimilar to the following:

/
|- public/
|- config/
|- application/

Regardless of your application's nature you would usually expect to have these directories; whether or not they exist is largely academic.

Capistrano relies on you having a config directory into which it will install a deploy.rb file that contains your settings.

The deploy.rb file is loaded when you call cap on the command line; in the event that you aren't in the root of your application (or more accurately that there isn't a capfile) in your present working directory, cap will search up the directory structure until it finds one, this may include your home directory.

Beware of this when dealing with multiple projects, or nested projects - this feature was intended so that you could run a deploy, or open a cap shell without moving to the root of your application.

Typically capifying an application will create something akin to the following:

set :application, "set your application name here"
set :repository,  "set your repository location here"

# If you aren't deploying to /u/apps/#{application} on the target
# servers (which is the default), you can specify the actual location
# via the :deploy_to variable:
# set :deploy_to, "/var/www/#{application}"

# If you aren't using Subversion to manage your source code, specify
# your SCM below:
# set :scm, :subversion

role :app, "your app-server here"
role :web, "your web-server here"
role :db,  "your db-server here", :primary => true

If your application is not separated into application, web and database servers, you can set them to be the same value (or comment out / remove the ones you don't need).

Often for a PHP application one of the web or app roles may be commented out, depending on your requirements. Certain built-in tasks expect to run only on one or the other kind of server.

The :primary => true part of the role definitions allows you to have more than one database server. This could also be written either of the following two ways: If you have two servers, and neither is primary:

role :db, 'db1.example.com', 'db2.example.com'
-- or --
role :db, 'db1.example.com', 'db2.example.com', :primary => true

If when deploying a Rails application you only want db1 to run migrations role :db, 'db1.example.com', :primary => true role :db, 'db2.example.com'

In the first example migrations may run on both servers. Essentially when using the Rails deployment recipes, the :primary option defines where database migrations are run.

Similar attributes include :no_release - often used for the :web role by some of the recipes in circulation to decide which servers should not have the code checked out to them.

Attributes like these are arbitrary and you can define some of your own, and use them to filter more precisely where your own tasks run.

You may want to read more about the role method as it has a few options. There is the alternate server method which works slightly differently, the examples should demonstrate this:

role :db, 'www.example.com'
role :app, 'www.example.com'
role :web, 'www.example.com'

And the server method:

server 'www.example.com', :app, :web, :db

If you have a lot of multi-function servers, or perhaps just one server running your whole application the server method may be a quick and easy way to remove a few LOC and a little confusion from your deployment configuration files.

Other than the shorter syntax, they are functionally equivalent.

Read next: Building Blocks Variables & Tasks or go back