Options for interacting with Docker.
Backend: <span style="color: purple"><code>pants.backend.docker</code></span> Config section: <span style="color: purple"><code>[docker]</code></span>
## Basic options
<div style="color: purple"> <h3><code>registries</code></h3> <code>--docker-registries="{'key1': val1, 'key2': val2, ...}"</code><br> <code>PANTS_DOCKER_REGISTRIES</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{}</code></span>
<br>
Configure Docker registries. The schema for a registry entry is as follows:
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"`.
</div> <br>
<div style="color: purple"> <h3><code>default_repository</code></h3> <code>--docker-default-repository=<str></code><br> <code>PANTS_DOCKER_DEFAULT_REPOSITORY</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>{name}</code></span>
<br>
Configure the default repository name used in the Docker image tag.
The value is formatted and may reference these variables (in addition to the normal placeheolders derived from the Dockerfile and build args etc):
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.
</div> <br>
<div style="color: purple"> <h3><code>default_context_root</code></h3> <code>--docker-default-context-root=<workspace_path></code><br> <code>PANTS_DOCKER_DEFAULT_CONTEXT_ROOT</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code></code></span>
<br>
Provide a default Docker build context root path for `docker_image` targets that does not specify their own `context_root` field.
The context root is relative to the build root by default, but may be prefixed with `./` to be relative to the directory of the BUILD file of the `docker_image`.
Examples:
</div> <br>
<div style="color: purple"> <h3><code>build_args</code></h3> <code>--docker-build-args="[<shell_str>, <shell_str>, ...]"</code><br> <code>PANTS_DOCKER_BUILD_ARGS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
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:
Use the `extra_build_args` field on a `docker_image` target for additional image specific build arguments.
</div> <br>
<div style="color: purple"> <h3><code>build_target_stage</code></h3> <code>--docker-build-target-stage=<str></code><br> <code>PANTS_DOCKER_BUILD_TARGET_STAGE</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>None</code></span>
<br>
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.
</div> <br>
<div style="color: purple"> <h3><code>build_verbose</code></h3> <code>--[no-]docker-build-verbose</code><br> <code>PANTS_DOCKER_BUILD_VERBOSE</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>False</code></span>
<br>
Whether to log the Docker output to the console. If false, only the image ID is logged.
</div> <br>
<div style="color: purple"> <h3><code>run_args</code></h3> <code>--docker-run-args="[<shell_str>, <shell_str>, ...]"</code><br> <code>PANTS_DOCKER_RUN_ARGS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
Additional arguments to use for `docker run` invocations.
Example:
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.
</div> <br>
## Advanced options
<div style="color: purple"> <h3><code>env_vars</code></h3> <code>--docker-env-vars="[<shell_str>, <shell_str>, ...]"</code><br> <code>PANTS_DOCKER_ENV_VARS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <code>[]</code></span>
<br>
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.
</div> <br>
<div style="color: purple"> <h3><code>executable_search_paths</code></h3> <code>--docker-executable-search-paths="[<binary-paths>, <binary-paths>, ...]"</code><br> <code>PANTS_DOCKER_EXECUTABLE_SEARCH_PATHS</code><br> </div> <div style="padding-left: 2em;"> <span style="color: green">default: <pre>[ "<PATH>" ]</pre></span>
<br>
The PATH value that will be used to find the Docker client and any tools required.
The special string `"<PATH>"` will expand to the contents of the PATH env var.
</div> <br>
## Deprecated options
None