Roles

Capistrano’s default recipe deploy.rb expects a number of default roles to be defined so that it may operate correctly.

:web	This is assumed to be your web servers (read: nginx / Apache / etc.)
:app	These are assumed to be your application servers, in a Ruby environment this means something like Unicorn, Passenger, Mongrel or Mongrel Cluster.
:db	This, naturally enough is your database server. You can use server/role modifiers below to control which is considered to be the primary one.

Populating Roles

role :app, 'app1.example.com'
role :app, 'app2.example.com', 'app3.example.com'
role :web, 'web1.example.com'

Notice that the role() method can take an array. You can read more in the API documentation here.

Modifiers

The default recipe knows about two modifiers. That’s to say extra configuration options that can be passed to role() to be used when specifying tasks.

:primary	true or false. Used by the database related tasks to determine where to run migrations
:no_release	true or false Used by the code checkout tasks to determine where to install the code. Anything set :no_release will not checkout the code from the repository.

The modifiers can be set in the following way:

role :db, 'db1.example.com', :primary => true, :no_release => false
role :db, 'db2.example.com', 'db3.example.com', :no_release => true

In the above example db1 will receive the code during the checkout due to :no_release => false (which is the default, or a no-op at least if it’s not true). Due to the :primary => true modifier the database migrations will be run here.

On the other db servers, no migrations will take place, and no code will be released. This is perfect for isolating your database slaves away from any code responsibility, or having to have a Ruby stack installed.

Defining your own roles.

You can select any arbitrary name which isn’t already reserved for your role names. The default recipe will ignore them but when writing your own tasks you can define your own modifiers and role names

Alternative Syntax

role() can also take a block, it is expected to return the options hash that would otherwise be expected.

In addition to role() there is also server which is for defining an individual server, and specifying a role; there are circumstances when this is preferable.

Servers playing multiple roles.

It is perfectly acceptable to have servers playing multiple roles:

role :app, 'example.com'
role :web, 'example.com'
role :db, 'example.com', :primary => true

However this is a nice use-case for the server() method, as you could simply write

server "example.com", :web, :app