Module: Capistrano::Configuration::Roles

Included in:
Capistrano::Configuration
Defined in:
lib/capistrano/configuration/roles.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#roles ⇒ Object (readonly)

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.



15
16
17
 
# File 'lib/capistrano/configuration/roles.rb', line 15

def roles
  @roles
end

Class Method Details

.included(base) ⇒ Object

:nodoc:



7
8
9
10
 
# File 'lib/capistrano/configuration/roles.rb', line 7

def self.included(base) #:nodoc:
  base.send :alias_method, :initialize_without_roles, :initialize
  base.send :alias_method, :initialize, :initialize_with_roles
end

Instance Method Details

#initialize_with_roles(*args) ⇒ Object

:nodoc:



17
18
19
20
 
# File 'lib/capistrano/configuration/roles.rb', line 17

def initialize_with_roles(*args) #:nodoc:
  initialize_without_roles(*args)
  @roles = Hash.new { |h,k| h[k] = Role.new }
end

#role(which, *args, &block) ⇒ Object

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,  "[email protected]"
role :file, "files.example.com:4144"
role :db,   "[email protected]: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



45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/capistrano/configuration/roles.rb', line 45

def role(which, *args, &block)
  options = args.last.is_a?(Hash) ? args.pop : {}
  which = which.to_sym

  # The roles Hash is defined so that unrecognized keys always auto-initialize
  # to a new Role instance (see the assignment in the initialize_with_roles method,
  # above). However, we explicitly assign here so that role declarations will
  # vivify the role object even if there are no server arguments. (Otherwise,
  # role(:app) won't actually instantiate a Role object for :app.)
  roles[which] ||= Role.new

  roles[which].push(block, options) if block_given?
  args.each { |host| roles[which] << ServerDefinition.new(host, options) }
end

#role_names_for_host(host) ⇒ Object 



72
73
74
 
# File 'lib/capistrano/configuration/roles.rb', line 72

def role_names_for_host(host)
  roles.map {|role_name, role| role_name if role.include?(host) }.compact || []
end

#server(host, *roles) ⇒ Object

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

Raises:

  • (ArgumentError) 


66
67
68
69
70
 
# File 'lib/capistrano/configuration/roles.rb', line 66

def server(host, *roles)
  options = roles.last.is_a?(Hash) ? roles.pop : {}
  raise ArgumentError, "you must associate a server with at least one role" if roles.empty?
  roles.each { |name| role(name, host, options) }
end