2.x-DSL-Configuration-Roles-Role.md

Definition

role(name, *servers, attributes={}, &block) 

Module

Capistrano::Configuration::Roles 

This method is the primary way to associate a server (or multiple servers) with a particular role. Servers may be associated with multiple roles--all a role does is allow servers to be selected based on the role they will play in a particular scenario. If a server participates in multiple roles, it will be selected whenever any of those roles are brought into play.

You can also associate a server with one or more roles via the server method.

Arguments

name

This should be a symbol identifying the name of the role. Typical role names are things like :app, :web, :db, or :mail; choose a name that makes sense for your configuration. If you use the same name in a subsequent role invocation, the second invocation will add to the prior one.

*servers

This argument (actually a list of arguments) is the servers to associate with the role. These will be strings, zero or more of them, of the following format: an optional username and "@" sign, followed by the name of the host, followed by an optional colon and port number. Some examples:

role :wiki, "wiki.social.com"
role :admin, "admin@social.com", "db.social.com:1234"

If a username is given, it overrides whatever setting was given for the user or ssh_options[:user] configuration variables. Likewise, if a port is given, it overrides whatever (if any) was specified in ssh_options[:port] configuration variable.

attributes

This must (if specified) be a Hash. It allows you to specify additional attributes for all the servers in this particular role declaration. (Other role declarations, even for the same role, will not automatically gain these attributes.) For example, you might have two database servers, one for the master database, and another for the slave. Rather than have two different roles (e.g. :dbmaster and :dbslave) you could have a single database role (:db) and differentiate the two based on an attribute:

role :db, "db.social.com", :master => true
role :db, "slave1.social.com"

Then, you can reference these attributes in your task definitions, or even directly in your run commands:

task :migrate, :roles => :db, :only => { :master => true } do
  # ...
end

task :other do
  run "migrate", :roles => :db, :only => { :master => true }
end

You can specify as many or as few of these attributes as you want; Capistrano itself does not predefine any of them (although the default deployment tasks do).

&block

If a block is given, it can be used to define a dynamic role. Usually, the servers in a role are immediately specified and associated, but sometimes you might not know the address of the server (or servers) that will participate in the role, at least not at the time you're writing the configuration. Some of these data might only be known at run-time, like in the example of using a cloud computing service like Amazon's EC2.

In that case, you can give a block to role. The first time the role is evaluated (typically the first time a command is executed), the block will be called, and the result appended to the other server definitions in the role. (The result is also cached, so the block is only evaluated once.)

The block may return either a string (formatted like you would pass as part of the servers argument), or a Capistrano::ServerDefinition object, or an array of either. Also, if you return an array, the last element of the array may be a Hash, in which case it is used as an attributes hash (see above), applicable only to the servers you are returning.

Some examples might make this clearer:

role(:web) { "apache@social.com" }
role(:web) { ["web3.social.com", "web3.social.com", {:backup => true}] }
role(:web) { compute_ec2_addresses }

Lastly, the block may accept a single argument, which will be the options hash that was passed to role:

role(:demo, :global => :yes) { |opts| ["web3.social.com", opts.merge(:backup => true)] }