Skip to main content
Version: 2.9 (deprecated)

docker

Options for interacting with Docker.

Backend: ``

Config section: [docker]

Basic options​

build_args​

--docker-build-args="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_BUILD_ARGS
pants.toml
[docker]
build_args = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Global build arguments (for Docker --build-arg options) to use for all docker build invocations.

Entries are either strings in the form ARG_NAME=value to set an explicit value; or just ARG_NAME to copy the value from Pants's own environment.

Example:

[docker]
build_args = ["VAR1=value", "VAR2"]

Use the extra_build_args field on a docker_image target for additional image specific build arguments.

build_target_stage​

--docker-build-target-stage=<str>
PANTS_DOCKER_BUILD_TARGET_STAGE
pants.toml
[docker]
build_target_stage = <str>
default: None

Global default value for target_stage on docker_image targets, overriding the field value on the targets, if there is a matching stage in the Dockerfile.

This is useful to provide from the command line, to specify the target stage to build for at execution time.

default_repository​

--docker-default-repository=<str>
PANTS_DOCKER_DEFAULT_REPOSITORY
pants.toml
[docker]
default_repository = <str>
default: {name}

Configure the default repository name used in the Docker image tag.

The value is formatted and may reference these variables:

  • name
  • directory
  • parent_directory

Example: --default-repository="{directory}/{name}".

The name variable is the docker_image's target name, directory and parent_directory are the name of the directory in which the BUILD file is for the target, and its parent directory respectively.

Use the repository field to set this value directly on a docker_image target. Any registries or tags are added to the image name as required, and should not be part of the repository name.

registries​

--docker-registries="{'key1': val1, 'key2': val2, ...}"
PANTS_DOCKER_REGISTRIES
pants.toml
[docker.registries]
key1 = val1
key2 = val2
...
default: {}

Configure Docker registries. The schema for a registry entry is as follows:

{
    "registry-alias": {
        "address": "registry-domain:port",
        "default": bool,
    },
    ...
}

If no registries are provided in a docker_image target, then all default addresses will be used, if any. The docker_image.registries may be provided with a list of registry addresses and registry aliases prefixed with @ to be used instead of the defaults. A configured registry is marked as default either by setting default = true or with an alias of "default".

run_args​

--docker-run-args="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_RUN_ARGS
pants.toml
[docker]
run_args = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Additional arguments to use for docker run invocations.

Example:

$ ./pants run --docker-run-args="-p 127.0.0.1:80:8080/tcp --name demo" src/example:image -- [image entrypoint args]

To provide the top-level options to the docker client, use [docker].env_vars to configure the Environment variables as appropriate.

The arguments for the image entrypoint may be passed on the command line after a double dash (--), or using the --run-args option.

Defaults to --interactive --tty when stdout is connected to a terminal.

Advanced options​

env_vars​

--docker-env-vars="[<shell_str>, <shell_str>, ...]"
PANTS_DOCKER_ENV_VARS
pants.toml
[docker]
env_vars = [
    <shell_str>,
    <shell_str>,
    ...,
]
default: []

Environment variables to set for docker invocations.

Entries are either strings in the form ENV_VAR=value to set an explicit value; or just ENV_VAR to copy the value from Pants's own environment.

Deprecated options​

None

None