Hey! These docs are for version 2.8, which is no longer officially supported. Click here for the latest version, 2.18!

## Configuring registries

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

Images built from this target will be published to these registries.

If you push many images to the same registries, and you don't want to repeat the endpoint information, you can name the registries in your `pants.toml` config file, and then refer to them by name in the target, using a `@` prefix.

You can also designate one or more registries as the default for your repo, and images with no explicit `registries` field will use those default registries.

## 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`:

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 supported 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.

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.

## 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`.

(Note that the field is named `image_tags` and not just `tags`, because Pants has [its own tags concept](🔗), 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.

Dynamically generated tags

Generating custom tags at runtime based on Git state or image inputs currently requires you to write some custom plugin code. Don't hesitate to [reach out](🔗) for help with this.

We are looking into adding this functionality into the core Docker plugin in the future.

## 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: