# docker plugin

## docker - stage files from Docker images

Usage:

    # Specify the docker source kind
    kind: docker

    # Specify the registry endpoint, defaults to Docker Hub (optional)
    registry-url: https://registry.hub.docker.com

    # Image path
    image: library/alpine

    # Alternatively, you can specify a full url, the registry endpoint
    # is assumed to be at the root of the domain
    # url: https://registry.hub.docker.com/library/alpine

    # Image tag to follow (optional)
    track: latest

    # Specify the digest of the exact image to use (required)
    ref: 6c9f6f68a131ec6381da82f2bff978083ed7f4f7991d931bfa767b7965ebc94b

    # Some images are built for multiple platforms. When tracking a tag, we
    # will choose which image to use based on these settings. Default values
    # are chosen based on the output of `uname -m` and `uname -s`, but you
    # can override them.
    #
    # architecture: arm64
    # os: linux
    #
    # **Since**: 2.0.1

    # Specify the version to be reported as the *guess_version* when reporting
    # SourceInfo
    #
    # Since: 2.5
    #
    version: 1.2

Note that Docker images may contain device nodes. BuildStream elements cannot contain device nodes so those will be dropped. Any regular files in the /dev directory will also be dropped.

See built-in functionality doumentation for details on common configuration options for sources.

### Reporting SourceInfo

The docker source reports the URL of the docker registry as the url.

Further, the docker source reports the SourceInfoMedium.OCI_IMAGE medium and the SourceVersionType.OCI_DIGEST version_type, for which it reports the content digest of the docker image as the version.

Additionally, the docker source reports the docker image name through the `image-name` key of the extra_data.

As such, after removing the scheme from the URL (i.e. remove `https://`) the same docker image can be obtained by calling:

    docker pull <url-without-scheme>/<image-name>@<version>

Since the docker source does not have any way to guess what tag is associated to the digest, or what release version that would mean; the docker source exposes the `version` configuration attribute to allow explicit specification of the guess_version.