Droppr Configuration

Configuration File Schema

A sample config file:

num_workers: 20
unpack_directory: /tmp

repos:
    - purl_type: maven
      target_type: nexus
      target_location: http://127.0.0.1:8081/repository/droppr_demo
      username: admin
      password_env: NEXUS_PW
      nexus:
         api_url:   http://127.0.0.1:8081
         repo_name: droppr_demo
        
      
    - purl_type: generic
      target_type: filesys
      file_system:
          target_directory: target/directory

    - purl_type: pypi
      regex_match: "pypi.org"
      target_type: local
      local_install:
          package_manager_command: ["python3", "-m", "pip"]

    - purl_type: pypi
      target_type: filesys
      file_system:
          target_directory: my/pypi/whls
    
    - purl_type: docker
      target_type: oci_registry
      username: user1
      password_env: OCI_PW
      oci_registry:
          host: myociregistry.io:5000
          project: my-docker-stuff
          tags: ["my-added-tag"]

Configuration Field Descriptions

num_workers:

• This field sets the number of worker threads to be used by Droppr. This value can be overridden by the --num_workers command line option, and will default to 10 if omitted.

unpack_directory:

• This field specifies where the bundle will be temporarily extracted on disk. Optional, and defaults to the OS temp directory (typically /tmp on Linux).

persist_directory:

• If this is set to true, then the directory that the extracted hoppr bundle is placed in will not be deleted after the code runs.

existing_directory:

• If provided, this field should be the path to a directory containing a hoppr bundle that was already extracted. droppr will use that bundle instead of doing its own extraction.

The repos field is an array of structures, with one entry per purl type. Each entry indicates how artifacts of that purl type are to be handled. The fields within each repo are:

• purl_type: The purl type being handled by this repo. Required

• regex_match: A regular expression to check against the source repository (the repository from which the artifact was originally copied) to use this repository. If omitted, it defaults to an empty string (which will always match). Note that the repository selected will always be the first successful match for a purl type, if there are multiple options. Therefore, the default (regex_match missing or "") should come last.

  • regex_match pattern matches can be referenced inside the following configuration fields:
    • target_directory fields (in both local_install: and file_system: target configurations - see below)
    • repo_name field in the nexus: target configuration

• target_type: Indicates how artifacts of this purl type are to be handled. Options are:

  • filesys, filesystem, file_sys, or file_system: Copy artifacts to a local directory
    • Must be accompanied with a file system target configuration (see below)
  • nexus: Install artifacts to a Nexus repository
    • Must be accompanied with a Nexus target configuration (see below)
  • local, localinstall, or local_install: Install the artifacts directly onto the local system
    • May be accompanied with a local install target configuration (see below)
  • oci_registry, oci_reg, or registry: Pushes Docker/Helm images to a registry that is compliant with the OCI Distribution Specification
    • Must be accompanied with a OCI registry target configuration (see below)
    • Note: This target type is only available for docker and helm purl types at this time.

• username: User to be used to access Nexus or OCI registry. Required for nexus or oci_registry, ignored otherwise.

• password_env: Environment variable containing the password to be used to access Nexus or an OCI registry. Required for nexus or oci_registry, ignored otherwise.

Target Type Configurations

• Depending on the desired target type, one of the following configuration structures (file_system:, local_install: , nexus:, or oci_registry:) is used in each repo entry to indicate how and where the artifacts are to be distributed. No more than 1 should be specified per repo entry.

File System Target Configuration

file_system:
    target_directory: {destinationDirectory}

• file_system: indicates where to copy artifact(s) to a file system. (Required when target_type is set to filesys)
  • target_directory Indicates the destination directory to write the artifact(s). (Required)
    • Can reference pattern matches ( e.g. $1, $2, etc...) from the regex_match if desired.

Local Install Target Configuration

local_install:
     package_manager_command: [{cmd},{arg0},...,{argn}]
     target_directory: {destinationDirectoryGitInstall}

• local_install: Indicates to install the artifact(s) directly to the local system. (May be used if target_type specifies local)

  • package_manager_command: Command (as an array of strings) used to access the appropriate package manager. Optional for local installs, ignored otherwise.
    • If omitted, a reasonable default command is used (e.g. pip for pypi artifiacts). If the pypi installation requires sudo access, and uses pip3 rather than pip, the value would be ["sudo", "pip3"].
  • target_directory: Indicates the target directory for PURL type 'git' installs. Otherwise ignored for all other PURL types.
    • Can reference pattern matches ( e.g. $1, $2, etc...) from the regex_match if desired.

Nexus Target Configuration

nexus:
    api_url: {NexusInstanceURL}
    repo_name: {NexusRepositoryName}
    docker_port: {portNumber}
    docker_protocol: {http|https}
    docker_url: {URLforDockerInteractions}
    apt_signing_keypair_file: {AptSigningFileName}

• nexus: Nexus installs only. Indicates where to install artifact(s) to a Nexus repository. (Required when target_type is set to nexus)
  • api_url: URL of the Nexus instance (e.g. https://my-nexus.com:8081)
  • repo_name: Repository name within a Nexus instance.
    • e.g. If your repository is located at https://my-nexus.com:8081/repository/my-repo, then repo_name should be set to my-repo
    • If the repository is not specified, a repository name will be generated based on the purl type (e.g. droppr_pypi)
    • Can reference pattern matches ( e.g. $1, $2, etc...) from the regex_match if desired.
  • docker_port: Specifies the port on the Nexus server for Docker processing.
    • Defaults to 5000
    • Ignored if docker_url is specified.
  • docker_protocol: Specifies the docker transfer protocol (http or https).
    • If not specified, defaults to the protocol specified in the api_url.
    • Ignored if docker_url is specified
  • docker_url: This is the URL to be used for docker interactions with the Nexus repository.
    • If specified, docker_port and docker_protocol are ignored, and the Nexus docker repository will be assumed valid and will not be created.
  • apt_signing_keypair_file: APT PURLs only. Specifies the GPG signature file for APT PURLs. Otherwise ignored.

OCI Target Configuration

oci_registry:
    host: {hostname[:port]}
    project: {top level project name}
    tags: [{tag1}, {tag2}, ... {tag n}]
    insecure: {true|false}

• oci_registry: OCI Registry installs only. Indicates where to install artifact(s) to an OCI registry. (Required when target_type is set to oci_registry)
  • host: (Required) Host of the OCI registry instance.
  • project: (Required) Project or top-level directory name within the registry.
    • Can reference pattern matches ( e.g. $1, $2, etc...) from the regex_match if desired.
  • tags: (Optional) List of tags to add to the image when pushing to the OCI registry
  • insecure: (Optional) Flag to indicate the access to the OCI registry is insecure (via http). Defaults to false if not specified.