Skip to content

extending-repositories.md

Latest commit

 

History

History
99 lines (75 loc) · 4.71 KB

extending-repositories.md

File metadata and controls

99 lines (75 loc) · 4.71 KB

Repositories

Many components need to have access to multiple versions of binaries. The buildpack provides a Repository abstraction to encapsulate version resolution and download URI creation.

Repository Structure

The repository is an HTTP-accessible collection of files. The repository root must contain an index.yml file (example) that is a mapping of concrete versions to absolute URIs consisting of a series of lines of the form:

<version>: <URI>

The collection of files may be stored alongside the index file or elsewhere.

An example filesystem might look like:

/index.yml
/openjdk-1.6.0_27.tar.gz
/openjdk-1.7.0_21.tar.gz
/openjdk-1.8.0_M7.tar.gz

Usage

The main class used when dealing with a repository is JavaBuildpack::Repository::ConfiguredItem. It provides a single method that is used to resolve a specific version and its URI.

# Finds an instance of the file based on the configuration and wraps any exceptions
# to identify the component.
#
# @param [String] component_name the name of the component
# @param [Hash] configuration the configuration
# @option configuration [String] :repository_root the root directory of the repository
# @option configuration [String] :version the version of the file to resolve
# @param [Block, nil] version_validator an optional version validation block
# @return [String] the URI of the chosen version of the file
# @return [JavaBuildpack::Util::TokenizedVersion] the chosen version of the file
def find_item(component_name, configuration)

Usage of the class might look like the following:

version, uri = JavaBuildpack::Repository::ConfiguredItem.find_item(configuration)

or with version validation:

version, uri = JavaBuildpack::Repository::ConfiguredItem.find_item(configuration) do |version|
  validate_version version
end

Wildcards

repository_root declarations in component configuration files can have variables in them. These variables are replaced by the repository infrastructure and the resulting URI is used when retrieving the repository index.

Variable Description
{default.repository.root} The common root for all repositories. Currently defaults to http://download.pivotal.io.s3.amazonaws.com.
{platform} The platform that the application is running on. Currently detects mountainlion, precise, and trusty.
{architecture} The architecture of the system as returned by Ruby. The value is typically one of x86_64 or x86.

Configuration

For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to Configuration and Extension.

Repositories can be configured by modifying the config/repository.yml file in the buildpack fork.

Name Description
default_repository_root This property can take a URI that is used as a common root for all of the repositories used by the buildpack. The value is substituted for the {default.repository.root} variable in repository_root declarations.

Proxies

Access to repositories may be affected by the existence of network proxies. In order to configure the buildpack to use a proxy, set the http_proxy, HTTP_PROXY, https_proxy, or HTTPS_PROXY environment variables with the property proxy URI. Proxy authentication crendentials can be embedded in the URI if needed.

cf set-env <APP_NAME> http_proxy http://username:password@host:port

Version Syntax and Ordering

Versions are composed of major, minor, micro, and optional qualifier parts (<major>.<minor>.<micro>[_<qualifier>]). The major, minor, and micro parts must be numeric. The qualifier part is composed of letters, digits, and hyphens. The lexical ordering of the qualifier is:

  1. hyphen
  2. lowercase letters
  3. uppercase letters
  4. digits

Version Wildcards

In addition to declaring a specific versions to use, you can also specify a bounded range of versions to use. Appending the + symbol to a version prefix chooses the latest version that begins with the prefix.

Example Description
1.+ Selects the greatest available version less than 2.0.0.
1.7.+ Selects the greatest available version less than 1.8.0.
1.7.0_+ Selects the greatest available version less than 1.7.1. Use this syntax to stay up to date with the latest security releases in a particular version.