Module: Capistrano::Configuration::Roles

Module | Capistrano::Configuration::Roles
In: | lib/capistrano/configuration/roles.rb lib/capistrano/configuration/roles.rb

### Methods

role role server server

### Attributes

roles | [R] | The hash of roles defined for this configuration. Each entry in the hash points to an array of server definitions that belong in that role.
roles | [R] | The hash of roles defined for this configuration. Each entry in the hash points to an array of server definitions that belong in that role.

### Public Instance methods

role(which, *args, &block)

Define a new role and its associated servers. You must specify at least one host for each role. Also, you can specify additional information (in the form of a Hash) which can be used to more uniquely specify the subset of servers specified by this specific role definition.

Usage:

      role :db,  "db1.example.com", "db2.example.com"
      role :db,  "master.example.com", :primary => true
      role :app, "app1.example.com", "app2.example.com"

You can also encode the username and port number for each host in the server string, if needed:

      role :web,  "www@web1.example.com"
      role :file, "files.example.com:4144"
      role :db,   "admin@db3.example.com:1234"

Lastly, username and port number may be passed as options, if that is preferred; note that the options apply to all servers defined in that call to "role":

      role :web, "web2", "web3", :user => "www", :port => 2345

[Source]

        # File lib/capistrano/configuration/roles.rb, line 45
    45:       def role(which, *args, &block)
    46:         options = args.last.is_a?(Hash) ? args.pop : {}
    47:         which = which.to_sym
    48:         roles[which].push(block, options) if block_given?
    49:         args.each { |host| roles[which] << ServerDefinition.new(host, options) }
    50:       end

role(which, *args, &block)

Define a new role and its associated servers. You must specify at least one host for each role. Also, you can specify additional information (in the form of a Hash) which can be used to more uniquely specify the subset of servers specified by this specific role definition.

Usage:

      role :db,  "db1.example.com", "db2.example.com"
      role :db,  "master.example.com", :primary => true
      role :app, "app1.example.com", "app2.example.com"

You can also encode the username and port number for each host in the server string, if needed:

      role :web,  "www@web1.example.com"
      role :file, "files.example.com:4144"
      role :db,   "admin@db3.example.com:1234"

Lastly, username and port number may be passed as options, if that is preferred; note that the options apply to all servers defined in that call to "role":

      role :web, "web2", "web3", :user => "www", :port => 2345

[Source]

        # File lib/capistrano/configuration/roles.rb, line 45
    45:       def role(which, *args, &block)
    46:         options = args.last.is_a?(Hash) ? args.pop : {}
    47:         which = which.to_sym
    48:         roles[which].push(block, options) if block_given?
    49:         args.each { |host| roles[which] << ServerDefinition.new(host, options) }
    50:       end

server(host, *roles)

An alternative way to associate servers with roles. If you have a server that participates in multiple roles, this can be a DRYer way to describe the relationships. Pass the host definition as the first parameter, and the roles as the remaining parameters:

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

[Source]

        # File lib/capistrano/configuration/roles.rb, line 58
    58:       def server(host, *roles)
    59:         options = roles.last.is_a?(Hash) ? roles.pop : {}
    60:         raise ArgumentError, "you must associate a server with at least one role" if roles.empty?
    61:         roles.each { |name| role(name, host, options) }
    62:       end

server(host, *roles)

An alternative way to associate servers with roles. If you have a server that participates in multiple roles, this can be a DRYer way to describe the relationships. Pass the host definition as the first parameter, and the roles as the remaining parameters:

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

[Source]

        # File lib/capistrano/configuration/roles.rb, line 58
    58:       def server(host, *roles)
    59:         options = roles.last.is_a?(Hash) ? roles.pop : {}
    60:         raise ArgumentError, "you must associate a server with at least one role" if roles.empty?
    61:         roles.each { |name| role(name, host, options) }
    62:       end

[Validate]