DocsCommunityTestimonialsUsersGitHubTwitterBlogJobs
HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.14, which is no longer officially supported. Click here for the latest version, 2.17!

## Configuring registries

A `docker_image` target takes an optional `registries` field, whose value is a list of registry endpoints and aliases:


When publising this image, it will be pushed to these registries by default.
In order to provide registry specific configuration, add them to the Pants configuration under
`[docker.registries.<alias>]` and refer to them by their alias from the `docker_image` targets,
using a `@` prefix.
Options for `registries` in `pants.toml`:
  • `address` - The registry endpoint.
  • `default` - Use this registry for all `docker_image` targets that does not provide a value for
the `registries` field. Multiple registries may be used as default at the same time.
  • `extra_image_tags` - Registry specific version tags to apply to the image when using this
registry.
  • `repository` - Format the repository part of the image name for this image. See [Setting a
repository name](doc:tagging-docker-images#setting-a-repository-name) for details of this option.
  • `skip_push` - Do not push images to this registry during `./pants publish`.
Example:

## Setting a repository name
In Docker parlance, an image is identified by a _repository_ and one or more _tags_ within that repository. 
You set a repository name using the `repository` field on `docker_image`:

To use a repository only for a specific registry, provide a `repository` value in the registry
configuration, and this can contain placeholders in curly braces that will be interpolated for each
image name.

You can also specify a default repository name in config, and this name can contain placeholders in
curly braces that will be interpolated for each `docker_image`:

The default placeholders are:
  • `{directory}`: The directory the docker_image's BUILD file is in.
  • `{parent_directory}`: The parent directory of `{directory}`.
  • `{name}`: The name of the docker_image target.
  • `{build_args.ARG_NAME}`: Each defined Docker build arg is available for interpolation under the `build_args.` prefix.
  • `{default_repository}`: The default repository from configuration.
  • `{target_repository}`: The repository on the `docker_image` if provided, otherwise the default repository.
Since repository names often conform to patterns like these, this can save you on some boilerplate
by allowing you to omit the `repository` field on each `docker_image`. But you can always override
this field on specific `docker_image` targets, of course. In fact, you can use these placeholders in
the `repository` field as well, if you find that helpful.
See [String interpolation using placeholder values](🔗) for more information.
## Tagging images
When Docker builds images, it can tag them with a set of tags. Pants will apply the tags listed in
the `image_tags` field of `docker_image`, and any additional tags if defined from the registry
configuration (see [Configuring registries](🔗).
(Note that the field is named `image_tags` and not just `tags`, because Pants has [its own tags
concept](doc:reference-target#codetagscode), which is unrelated.)

When pants builds the `src/example:demo` target, a single image will be built, with two tags applied:
  • `example/demo:1.2`
  • `example/demo:example`
It's often useful to keep versions of derived images and their base images in sync. Pants helps you
out with this by interpolating tags referenced in `FROM` commands in your Dockerfile into the
`image_tags` in the corresponding `docker_image`:

This way you can specify a version just once, on the base image, and the derived images will
automatically acquire the same version.
You may also use any Docker build arguments (when configured as described in [Docker build
arguments](doc:docker#build-arguments)) for interpolation into the `image_tags` in the corresponding
`docker_image`:

## Using env vars to include dynamic data in tags
You can interpolate dynamic data, such as the current Git commit sha, in an image tag, using environment variables and Docker build args.
For example, you can declare a custom build arg, either in `extra_build_args` for a specific `docker_image` target, or for all `docker_image` targets in `pants.toml`:

and use this build arg in the image tag:

Then, if you run Pants with the data set in an environment variable of the same name:

the value from the environment will be used. 
Generating dynamic tags in a plugin
If you don't want to use the environment variable method described above, you'll need to write some custom plugin code. Don't hesitate to [reach out](🔗) for help with this.
We are looking into making some common dynamic data, such as the git sha, automatically available in the core Docker plugin in the future.
## Providing additional image tags with a plugin
For cases where more customization is required and using environment variables and interpolation is
not enough, the next option is to write a plugin to provide additional tags when building images.
Demonstrated with an example:

## All together: Registries, Repositories and Tags
To illustrate how all the above work together, this target:

Will create a single image with these full names:

## String interpolation using placeholder values
As we've seen above, some fields of the `docker_image` support replacing placeholder values in curly braces with variable text, such as a build arg or base image tag for instance.
The interpolation context (the available placeholder values) depends on which field it is used in. These are the common values available for all fields:
  • `{tags.<stage>}`: The tag of a base image (the `FROM` instruction) for a particular stage in the `Dockerfile`. The `<stage>` is either `stageN` where `N` is the numeric index of the stage, starting at `0`. The first stage, `stage0`, is also available under the pseudonym `baseimage`. If the stage is named (`FROM image AS my_stage`), then the tag value is also available under that name: `{tags.my_stage}`.
  • `{build_args.ARG_NAME}`: Each defined Docker build arg is available for interpolation under the `build_args.` prefix.
  • `{pants.hash}`: This is a unique hash value calculated from all input sources and the `Dockerfile`. It is effectively a hash of the Docker build context. See note below regarding its stability guarantee.
See [Setting a repository name](🔗) for placeholders specific to the `repository` field.
The `{pants.hash}` stability guarantee
The calculated hash value _may_ change between stable versions of Pants for the otherwise same input sources.