Module Capistrano::Configuration::Servers
In: lib/capistrano/configuration/servers.rb
lib/capistrano/configuration/servers.rb

Methods

Public Instance methods

Attempts to find all defined servers that match the given criteria. The options hash may include a :hosts option (which should specify an array of host names or ServerDefinition instances), a :roles option (specifying an array of roles), an :only option (specifying a hash of key/value pairs that any matching server must match), and an :exception option (like :only, but the inverse).

Additionally, if the HOSTS environment variable is set, it will take precedence over any other options. Similarly, the ROLES environment variable will take precedence over other options. If both HOSTS and ROLES are given, HOSTS wins.

Usage:

  # return all known servers
  servers = find_servers

  # find all servers in the app role that are not exempted from
  # deployment
  servers = find_servers :roles => :app,
               :except => { :no_release => true }

  # returns the given hosts, translated to ServerDefinition objects
  servers = find_servers :hosts => "jamis@example.host.com"

[Source]

    # File lib/capistrano/configuration/servers.rb, line 36
36:       def find_servers(options={})
37:         hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
38:         roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
39:         only   = options[:only] || {}
40:         except = options[:except] || {}
41: 
42:         if hosts.any?
43:           hosts.uniq
44:         else
45:           servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
46:           servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
47:           servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
48:           servers.uniq
49:         end
50:       end

Attempts to find all defined servers that match the given criteria. The options hash may include a :hosts option (which should specify an array of host names or ServerDefinition instances), a :roles option (specifying an array of roles), an :only option (specifying a hash of key/value pairs that any matching server must match), and an :exception option (like :only, but the inverse).

Additionally, if the HOSTS environment variable is set, it will take precedence over any other options. Similarly, the ROLES environment variable will take precedence over other options. If both HOSTS and ROLES are given, HOSTS wins.

Usage:

  # return all known servers
  servers = find_servers

  # find all servers in the app role that are not exempted from
  # deployment
  servers = find_servers :roles => :app,
               :except => { :no_release => true }

  # returns the given hosts, translated to ServerDefinition objects
  servers = find_servers :hosts => "jamis@example.host.com"

[Source]

    # File lib/capistrano/configuration/servers.rb, line 36
36:       def find_servers(options={})
37:         hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
38:         roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
39:         only   = options[:only] || {}
40:         except = options[:except] || {}
41: 
42:         if hosts.any?
43:           hosts.uniq
44:         else
45:           servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
46:           servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
47:           servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
48:           servers.uniq
49:         end
50:       end

Identifies all servers that the given task should be executed on. The options hash accepts the same arguments as find_servers, and any preexisting options there will take precedence over the options in the task.

[Source]

    # File lib/capistrano/configuration/servers.rb, line 8
 8:       def find_servers_for_task(task, options={})
 9:         find_servers(task.options.merge(options))
10:       end

Identifies all servers that the given task should be executed on. The options hash accepts the same arguments as find_servers, and any preexisting options there will take precedence over the options in the task.

[Source]

    # File lib/capistrano/configuration/servers.rb, line 8
 8:       def find_servers_for_task(task, options={})
 9:         find_servers(task.options.merge(options))
10:       end

Protected Instance methods

[Source]

    # File lib/capistrano/configuration/servers.rb, line 70
70:       def build_list(list)
71:         Array(list).map { |item| item.respond_to?(:call) ? item.call : item }.flatten
72:       end

[Source]

    # File lib/capistrano/configuration/servers.rb, line 70
70:       def build_list(list)
71:         Array(list).map { |item| item.respond_to?(:call) ? item.call : item }.flatten
72:       end

[Source]

    # File lib/capistrano/configuration/servers.rb, line 60
60:       def role_list_from(roles)
61:         roles = roles.split(/,/) if String === roles
62:         roles = build_list(roles)
63:         roles.map do |role|
64:           role = String === role ? role.strip.to_sym : role
65:           raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
66:           role
67:         end
68:       end

[Source]

    # File lib/capistrano/configuration/servers.rb, line 60
60:       def role_list_from(roles)
61:         roles = roles.split(/,/) if String === roles
62:         roles = build_list(roles)
63:         roles.map do |role|
64:           role = String === role ? role.strip.to_sym : role
65:           raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
66:           role
67:         end
68:       end

[Source]

    # File lib/capistrano/configuration/servers.rb, line 54
54:       def server_list_from(hosts)
55:         hosts = hosts.split(/,/) if String === hosts
56:         hosts = build_list(hosts)
57:         hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
58:       end

[Source]

    # File lib/capistrano/configuration/servers.rb, line 54
54:       def server_list_from(hosts)
55:         hosts = hosts.split(/,/) if String === hosts
56:         hosts = build_list(hosts)
57:         hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
58:       end

[Validate]