Module: Capistrano::Configuration::Servers

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

### Methods

build_list build_list filter_server_list filter_server_list find_servers find_servers find_servers_for_task find_servers_for_task role_list_from role_list_from server_list_from server_list_from

### Public Instance methods

find_servers(options={})

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.

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 41
    41:       def find_servers(options={})
    42:         hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
    43:
    44:         if hosts.any?
    45:           if options[:skip_hostfilter]
    46:             hosts.uniq
    47:           else
    48:             filter_server_list(hosts.uniq)
    49:           end
    50:         else
    51:           roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
    52:           only   = options[:only] || {}
    53:           except = options[:except] || {}
    54:
    55:           servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
    56:           servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
    57:           servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
    58:
    59:           if options[:skip_hostfilter]
    60:             servers.uniq
    61:           else
    62:             filter_server_list(servers.uniq)
    63:           end
    64:         end
    65:       end

find_servers(options={})

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.

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 41
    41:       def find_servers(options={})
    42:         hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
    43:
    44:         if hosts.any?
    45:           if options[:skip_hostfilter]
    46:             hosts.uniq
    47:           else
    48:             filter_server_list(hosts.uniq)
    49:           end
    50:         else
    51:           roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
    52:           only   = options[:only] || {}
    53:           except = options[:except] || {}
    54:
    55:           servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
    56:           servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
    57:           servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
    58:
    59:           if options[:skip_hostfilter]
    60:             servers.uniq
    61:           else
    62:             filter_server_list(servers.uniq)
    63:           end
    64:         end
    65:       end

find_servers_for_task(task, options={})

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

find_servers_for_task(task, options={})

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

build_list(list)

[Source]

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

build_list(list)

[Source]

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

filter_server_list(servers)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 69
    69:       def filter_server_list(servers)
    70:         return servers unless ENV['HOSTFILTER']
    71:         filters = ENV['HOSTFILTER'].split(/,/)
    72:         servers.select { |server| filters.include?(server.host) }
    73:       end

filter_server_list(servers)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 69
    69:       def filter_server_list(servers)
    70:         return servers unless ENV['HOSTFILTER']
    71:         filters = ENV['HOSTFILTER'].split(/,/)
    72:         servers.select { |server| filters.include?(server.host) }
    73:       end

role_list_from(roles)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 81
    81:       def role_list_from(roles)
    82:         roles = roles.split(/,/) if String === roles
    83:         roles = build_list(roles)
    84:         roles.map do |role|
    85:           role = String === role ? role.strip.to_sym : role
    86:           raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
    87:           role
    88:         end
    89:       end

role_list_from(roles)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 81
    81:       def role_list_from(roles)
    82:         roles = roles.split(/,/) if String === roles
    83:         roles = build_list(roles)
    84:         roles.map do |role|
    85:           role = String === role ? role.strip.to_sym : role
    86:           raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
    87:           role
    88:         end
    89:       end

server_list_from(hosts)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 75
    75:       def server_list_from(hosts)
    76:         hosts = hosts.split(/,/) if String === hosts
    77:         hosts = build_list(hosts)
    78:         hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
    79:       end

server_list_from(hosts)

[Source]

        # File lib/capistrano/configuration/servers.rb, line 75
    75:       def server_list_from(hosts)
    76:         hosts = hosts.split(/,/) if String === hosts
    77:         hosts = build_list(hosts)
    78:         hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
    79:       end

[Validate]