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), an :exception option (like :only, but the inverse), and a :skip_hostfilter option to ignore the HOSTFILTER environment variable described below.
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.
Yet additionally, if the HOSTFILTER environment variable is set, it will limit the result to hosts found in that (comma-separated) list.
If the HOSTROLEFILTER environment variable is set, it will limit the result to hosts found in that (comma-separated) list of roles
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"
# File lib/capistrano/configuration/servers.rb, line 44 44: def find_servers(options={}) 45: return [] if options.key?(:hosts) && (options[:hosts].nil? || [] == options[:hosts]) 46: return [] if options.key?(:roles) && (options[:roles].nil? || [] == options[:roles]) 47: 48: hosts = server_list_from(ENV['HOSTS'] || options[:hosts]) 49: 50: if hosts.any? 51: if options[:skip_hostfilter] 52: hosts.uniq 53: else 54: filter_server_list(hosts.uniq) 55: end 56: else 57: roles = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys) 58: roles = roles & Array(options[:roles]) if preserve_roles && !options[:roles].nil? 59: 60: only = options[:only] || {} 61: except = options[:except] || {} 62: 63: # If we don't have a def for a role it means its bogus, skip it so higher level can handle 64: servers = roles.inject([]) { |list, role| list.concat(self.roles[role] || []) } 65: servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } } 66: servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } } 67: 68: if options[:skip_hostfilter] 69: servers.uniq 70: else 71: filter_server_list(servers.uniq) 72: end 73: end 74: end
Identifies all servers that the given task should be executed on. The options hash accepts the same arguments as #, and any preexisting options there will take precedence over the options in the task.
# 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
# File lib/capistrano/configuration/servers.rb, line 111 111: def build_list(list) 112: Array(list).map { |item| item.respond_to?(:call) ? item.call : item }.flatten 113: end
# File lib/capistrano/configuration/servers.rb, line 78 78: def filter_server_list(servers) 79: return servers unless ENV['HOSTFILTER'] or ENV['HOSTROLEFILTER'] 80: if ENV['HOSTFILTER'] 81: filters = ENV['HOSTFILTER'].split(/,/) 82: servers.select { |server| filters.include?(server.host) } 83: elsif ENV['HOSTROLEFILTER'] 84: filters = ENV['HOSTROLEFILTER'].split(/,/).map do |role| 85: local_roles = roles[role.to_sym] 86: if local_roles.is_a? Array 87: roles[role.to_sym] 88: else 89: roles[role.to_sym].servers 90: end 91: end.flatten 92: servers.select { |server| filters.include?(server) } 93: end 94: end
# File lib/capistrano/configuration/servers.rb, line 102 102: def role_list_from(roles) 103: roles = roles.split(/,/) if String === roles 104: roles = build_list(roles) 105: roles.map do |role| 106: role = String === role ? role.strip.to_sym : role 107: role 108: end 109: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.