> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/docker

Quickly and easily install/configure/use Docker, `dockerize`, and `docker-compose` in any CircleCI job.


## Commands

### build

Build and tag a Docker image


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_at` | string |  | Provide a path if you wish to attach a workspace. Use `./` for the working directory. `attach_workspace` attached location - where to mount folder/files that were `persist_to_workspace` in a previous step. https://circleci.com/docs/2.0/configuration-reference/#attach_workspace
 |
| `cache_from` | string |  | A list of cache storage backends separated by space. You can use the full syntax: type=registry,ref=<registry>/<cache-image>[,parameters...] Or the compact syntax: ref=<registry>/<cache-image>
 |
| `cache_to` | string |  | A list of cache storage backends separated by space. You can use the full syntax: type=registry,ref=<registry>/<cache-image>[,parameters...] Or the compact syntax: ref=<registry>/<cache-image>
 |
| `docker_context` | string | . | Path to the directory containing your build context, defaults to . (working directory)
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use, defaults to Dockerfile |
| `extra_build_args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build. Pass the desired args using an equal sign (=) instead of an space. For example, --build-arg=ARG1=value, instead of --build-arg ARG1=vallue.
 |
| `image` | string |  | Name of image to build |
| `lint_dockerfile` | boolean | false | Lint Dockerfile before building?
 |
| `no_output_timeout` | string | 10m | Pass through a default timeout if your Docker build does not output anything for more than 10 minutes.
 |
| `path` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `registry` | string | docker.io | Name of registry to use, defaults to docker.io
 |
| `step_name` | string | Docker build | Specify a custom step name for this command, if desired |
| `tag` | string | $CIRCLE_SHA1 | Image tag, defaults to the value of $CIRCLE_SHA1 |
| `treat_warnings_as_errors` | boolean | false | If linting Dockerfile, treat linting warnings as errors? (would trigger an exit code and fail the CircleCI job)
 |
| `use_buildkit` | boolean | false | Use buildkit to build the image. Available on Docker >= 18.09.0 https://docs.docker.com/develop/develop-images/build_enhancements/
 |

### check

Sanity check to make sure you can build a Docker image. Check that Docker username and password environment variables are set, then run docker login to ensure that you can push the built image


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arch` | enum | amd64 | Which architecture is being used.
Values accepted are amd64 and arm64. Defaults to amd64.
When running on MacOS arm64 will be used.
 |
| `docker_password` | env_var_name | DOCKER_PASSWORD | Name of environment variable storing your Docker password
 |
| `docker_username` | env_var_name | DOCKER_LOGIN | Name of environment variable storing your Docker username
 |
| `registry` | string | docker.io | Name of registry to use, defaults to docker.io |
| `use_docker_credentials_store` | boolean | false | Configure Docker to use a credentials store. This option is only supported on Ubuntu/Debian/macOS platforms.
 |

### configure_docker_credentials_store

Configure a credentials store for docker to use. See: https://docs.docker.com/engine/reference/commandline/login/#credentials-store#credentials-store Supported platforms: Linux and macOS.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `docker_config_path` | string | $HOME/.docker/config.json | Path to the Docker CLI config file.
 |
| `helper_name` | enum |  | Name of the credential helper to be used, e.g. "pass". If left blank, the orb will attempt to choose one based on the platform.
 |

### hadolint

Lint a given Dockerfile using hadolint. If the hadolint docker image is not used, hadolint will be installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `dockerfiles` | string | Dockerfile | Relative or absolute path, including name, to Dockerfile(s) to be linted, e.g., `~/project/app/deploy.Dockerfile`, defaults to a Dockerfile named `Dockerfile` in the working directory. To lint multiple Dockerfiles, pass a colon-separated string, e.g., `~/project/app/deploy.Dockerfile:~/project/app/test.Dockerfile`.
 |
| `failure_threshold` | enum | info | Hadolint threshold level to fail on. Exit with failure code only when rules with a severity equal to or above THRESHOLD are violated
 |
| `ignore_rules` | string |  | Comma-separated string list of rules to ignore (e.g., `DL3000,SC1010`): https://github.com/hadolint/hadolint#rules
 |
| `trusted_registries` | string |  | Comma-separated list of trusted registries (e.g., `docker.io,my-company.com:5000`); if set, return an error if Dockerfiles use any images from registries not included in this list
 |

### install_docker

Install the Docker CLI. Supports stable versions `v17.06.0-ce` and newer, on all platforms (Linux, macOS). Requirements: curl, grep, jq, tar


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install_dir` | string | /usr/local/bin | Directory in which to install Docker binaries
 |
| `version` | string | latest | Version of Docker to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://api.github.com/repos/docker/cli/tags, e.g., `v18.09.4`.
 |

### install_docker_compose

Install the `docker-compose` CLI. Supports stable versions. Requirements: curl, Docker, grep, jq, sha256sum,


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install_dir` | string | /usr/local/bin | Directory in which to install `docker-compose`
 |
| `version` | string | latest | Version of `docker-compose` to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/docker/compose/releases or https://api.github.com/repos/docker/compose/releases, e.g., `v2.10.0`. Only versions equal or above v2.0.1 are supported.
 |

### install_docker_credential_helper

Install a credential helper for Docker, automatically chosen based on platform detection. See: https://docs.docker.com/engine/reference/commandline/login/#credentials-store#credential-helpers Supported platforms: Ubuntu/Debian and macOS.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arch` | enum | amd64 | Which architecture is being used.
Values accepted are amd64 and arm64. Defaults to amd64.
When running on MacOS arm64 will be used.
 |
| `helper_name` | enum |  | Name of the credential helper to be installed, e.g. "pass". If left blank, the orb will attempt to choose one based on the platform.
 |
| `release_tag` | string |  | Use this to specify a tag to select which published release of the docker credential helper, as listed on https://github.com/docker/docker-credential-helpers/releases, to install. If no value is specified, the latest release will be installed. Note: Pre or alpha releases cannot be specified.
 |

### install_docker_tools

Install commonly used Docker tools (Docker, `docker-compose`, `dockerize`). Requirements: curl, grep, jq, sha256sum, tar


| Parameter | Type | Default | Description |
|---|---|---|---|
| `debug` | boolean | false | Extra output for orb developers
 |
| `docker_compose_install_dir` | string | /usr/local/bin | Directory in which to install `docker-compose`
 |
| `docker_compose_version` | string | latest | Version of `docker-compose` to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/docker/compose/releases or https://api.github.com/repos/docker/compose/releases, e.g., `1.23.1`.
 |
| `docker_install_dir` | string | /usr/local/bin | Directory in which to install Docker binaries
 |
| `docker_version` | string | latest | Version of Docker to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://api.github.com/repos/docker/cli/tags, e.g., `v18.09.4`.
 |
| `dockerize_install_dir` | string | /usr/local/bin | Directory in which to install `dockerize`
 |
| `dockerize_version` | string | latest | Version of `dockerize` to install, defaults to the latest release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/jwilder/dockerize/releases, e.g., `v0.5.0`. Supports versions `v.0.4.0` and later.
 |
| `goss_architecture` | enum | amd64 | Which Goss architecture to use. Supports `arm64` architecture from `v0.3.18` and newer.
 |
| `goss_install_dir` | string | /usr/local/bin | Directory in which to install Goss and `dgoss`
 |
| `goss_version` | string | latest | Version of Goss and `dgoss` to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/aelsabbahy/goss/releases or https://api.github.com/repos/aelsabbahy/goss/releases, e.g., `v0.3.7`.
 |
| `install_docker` | boolean | true | Install the Docker CLI? Supports stable versions `v17.06.0-ce` and newer, on all platforms (Linux, macOS). Requirements: curl, grep, jq, tar
 |
| `install_docker_compose` | boolean | true | Install the `docker-compose` CLI? Supports stable versions. Requirements: curl, Docker, grep, jq, sha256sum
 |
| `install_dockerize` | boolean | true | Install `dockerize`? Supports versions `v.0.4.0` and later. Requirements: curl, Docker
 |
| `install_goss_dgoss` | boolean | true | Install Goss and `dgoss`?
 |

### install_dockerize

Install `dockerize`. Supports versions `v.0.4.0` and later. Requirements: curl, Docker


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install_dir` | string | /usr/local/bin | Directory in which to install `dockerize`
 |
| `version` | string | latest | Version of `dockerize` to install, defaults to the latest release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/jwilder/dockerize/releases, e.g., `v0.5.0`. Supports versions `v.0.4.0` and later.
 |

### install_goss

Install the Goss and `dgoss` CLI tools, commonly using for testing Docker containers. Only compatible with Linux-based execution environments. More info: https://github.com/aelsabbahy/goss https://github.com/aelsabbahy/goss/tree/master/extras/dgoss


| Parameter | Type | Default | Description |
|---|---|---|---|
| `architecture` | enum | amd64 | Which Goss architecture to use. Supports `arm64` architecture from `v0.3.18` and newer.
 |
| `debug` | boolean | false | Extra output for orb developers
 |
| `install_dir` | string | /usr/local/bin | Directory in which to install Goss and `dgoss`
 |
| `version` | string | latest | Version of Goss and `dgoss` to install, defaults to the latest stable release. If specifying a version other than latest, provide a full release tag, as listed at https://github.com/aelsabbahy/goss/releases or https://api.github.com/repos/aelsabbahy/goss/releases, e.g., `v0.3.7`. Supports versions `v0.3.1` and newer.
 |

### pull

Pull one or more Docker images from a registry

| Parameter | Type | Default | Description |
|---|---|---|---|
| `ignore_docker_pull_error` | boolean | false | Ignores errors from docker pull command |
| `images` | string |  | Comma-separated list of images to pull |

### push

Push a Docker image to a registry

| Parameter | Type | Default | Description |
|---|---|---|---|
| `digest_path` | string |  | The path to save the RepoDigest of the pushed image |
| `image` | string |  | Name of image to push |
| `registry` | string | docker.io | Name of registry to use, defaults to docker.io
 |
| `step_name` | string | Docker push | Specify a custom step name for this command, if desired |
| `tag` | string | $CIRCLE_SHA1 | Comma-separated list of image tag, defaults to the value of $CIRCLE_SHA1 |

### update_description

Update a Docker image's description on Docker Hub

| Parameter | Type | Default | Description |
|---|---|---|---|
| `docker_password` | env_var_name | DOCKER_PASSWORD | Name of environment variable storing your Docker password
 |
| `docker_username` | env_var_name | DOCKER_LOGIN | Name of environment variable storing your Docker username
 |
| `image` | string |  | Name of image to push |
| `path` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `readme` | string | README.md | Name of the file containing the image description to update, defaults to README.md |
| `registry` | string | docker.io | Name of registry to use, defaults to docker.io
 |

## Jobs

### hadolint

Lint a given Dockerfile using a hadolint Docker image: https://hub.docker.com/r/hadolint/hadolint


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach_workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace, default is false
 |
| `checkout` | boolean | true | Checkout as a first step? Default is true |
| `dockerfiles` | string | Dockerfile | Relative or absolute path, including name, to Dockerfile(s) to be linted, e.g., `~/project/app/deploy.Dockerfile`, defaults to a Dockerfile named `Dockerfile` in the working directory. To lint multiple Dockerfiles, pass a colon-separated string, e.g., `~/project/app/deploy.Dockerfile:~/project/app/test.Dockerfile`.
 |
| `executor_class` | enum | small | Resource class to use for the hadolint executor |
| `failure_threshold` | enum | info | Hadolint threshold level to fail on. Exit with failure code only when rules with a severity equal to or above THRESHOLD are violated
 |
| `hadolint_tag` | string | latest-debian | Specific Hadolint image (make sure to use a `debian` tag, otherwise image will not be usable on CircleCI): https://hub.docker.com/r/hadolint/hadolint/tags
 |
| `ignore_rules` | string |  | Comma-separated string list of rules to ignore (e.g., `DL3000,SC1010`): https://github.com/hadolint/hadolint#rules
 |
| `trusted_registries` | string |  | Comma-separated list of trusted registries (e.g., `docker.io,my-company.com:5000`); if set, return an error if Dockerfiles use any images from registries not included in this list
 |
| `workspace_root` | string | workspace | Workspace root path that is either an absolute path or a path relative to the working directory
 |

### publish

Build and optionally deploy a Docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `after_build` | steps |  | Optional steps to run after building the Docker image |
| `after_checkout` | steps |  | Optional steps to run after checking out the code |
| `attach_at` | string |  | Provide a path if you wish to attach a workspace. Use `./` for the working directory. `attach_workspace` attached location - where to mount folder/files that were `persist_to_workspace` in a previous step. https://circleci.com/docs/2.0/configuration-reference/#attach_workspace
 |
| `before_build` | steps |  | Optional steps to run before building the Docker image |
| `cache_from` | string |  | A list of cache storage backends separated by space. You can use the full syntax: type=registry,ref=<registry>/<cache-image>[,parameters...] Or the compact syntax: ref=<registry>/<cache-image>
 |
| `cache_to` | string |  | A list of cache storage backends separated by space. You can use the full syntax: type=registry,ref=<registry>/<cache-image>[,parameters...] Or the compact syntax: ref=<registry>/<cache-image>
 |
| `deploy` | boolean | true | Push the image to a registry? |
| `docker_context` | string | . | Path to the directory containing your build context, defaults to . (working directory)
 |
| `docker_password` | env_var_name | DOCKER_PASSWORD | Name of environment variable storing your Docker password
 |
| `docker_username` | env_var_name | DOCKER_LOGIN | Name of environment variable storing your Docker username
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use, defaults to Dockerfile |
| `executor` | executor | machine | Executor to use for this job, defaults to this orb's `machine` executor
 |
| `extra_build_args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build Pass the desired args using an equal sign (=) instead of an space. For example, --build-arg=ARG1=value, instead of --build-arg ARG1=vallue.
 |
| `image` | string |  | Name of image to build |
| `lint_dockerfile` | boolean | false | Lint Dockerfile before building?
 |
| `path` | string | . | Path to the directory containing your Dockerfile, defaults to . (working directory)
 |
| `readme` | string | README.md | Name of the file containing the image description to update, defaults to README.md |
| `registry` | string | docker.io | Name of registry to use, defaults to docker.io
 |
| `remote_docker_dlc` | boolean | false | Enable docker layer caching if using remote Docker engine. Defaults to false.
 |
| `remote_docker_version` | string | default | Pick remote Docker engine version. Available versions can be found at: https://circleci.com/docs/2.0/building-docker-images/#docker_version. Must be >= 18.09 for BuildKit support.
 |
| `tag` | string | $CIRCLE_SHA1 | Comma-separated list of image tags, defaults to the value of $CIRCLE_SHA1 |
| `treat_warnings_as_errors` | boolean | false | If linting Dockerfile, treat linting warnings as errors (would trigger an exist code and fail the CircleCI job)?
 |
| `update_description` | boolean | false | Update the image description on Docker Hub? |
| `use_buildkit` | boolean | false | Use buildkit to build the image. Available on Docker >= 18.09.0 https://docs.docker.com/develop/develop-images/build_enhancements/
 |
| `use_docker_credentials_store` | boolean | false | Configure Docker to use a credentials store. This option is only supported on Ubuntu/Debian platforms.
 |
| `use_remote_docker` | boolean | false | Setup a remote Docker engine for Docker commands? Only required if using a Docker-based executor
 |

## Executors

### docker

The docker container to use when running this orb's jobs


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image` | string | cimg/python | Docker image name |
| `tag` | string | 3.13 | Image tag |

### hadolint

Hadolint Docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | small |  |
| `tag` | string | latest-debian | Specific Hadolint image (make sure to use a `debian` tag, otherwise image will not be usable on CircleCI): https://hub.docker.com/r/hadolint/hadolint/tags
 |

### machine

CircleCI's Ubuntu-based machine executor VM: https://circleci.com/docs/2.0/executor-types/#using-machine


| Parameter | Type | Default | Description |
|---|---|---|---|
| `dlc` | boolean | false | Enable Docker Layer Caching? |
| `image` | string | ubuntu-2204:current |  |
| `resource_class` | enum | medium | Resource class. |

## Examples

### build_and_update

Build and publish, and update the description of an image using the publish job


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          update_description: true
  build-docker-image-only-with-buildkit:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          remote_docker_version: 20.10.12
          update_description: true
          use_buildkit: true
          use_remote_docker: true
```

### build_push_digest

Build and push an image, save the digest to a file and echo the file.


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
jobs:
  build-and-push:
    executor: docker/docker
    steps:
      - setup_remote_docker
      - checkout
      - docker/check
      - docker/build:
          image: my_repo/orb-test
      - docker/push:
          digest_path: /tmp/digest.txt
          image: my_repo/orb-test
      - run:
          command: |
            echo "Digest is: $(</tmp/digest.txt)"
workflows:
  commit:
    jobs:
      - build-and-push
```

### build_without_publishing

Build, but don't publish, an image using the publish job


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          deploy: false
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
```

### build_without_publishing_commands

Build, but don't publish, an image using the check and build commands


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
jobs:
  check-and-build-only:
    executor: docker/machine
    steps:
      - checkout
      - docker/check
      - docker/build:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
workflows:
  build-docker-image-only:
    jobs:
      - check-and-build-only
```

### custom_name_tag_executor

Build and Deploy docker image with a custom name and tag, using a non-default executor with custom parameter values (note: when using a Docker-based excecutor, the `use_remote_docker` parameter must be set to true in order for Docker commands to run successfully).


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          executor:
            image: circleci/node
            name: docker/docker
            tag: boron-browsers
          image: my/image
          remote_docker_dlc: true
          tag: my-tag
          use_remote_docker: true
```

### custom_pull

Use the pull command to pull one or more Docker images


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
  jobs:
    pull:
      executor: docker/machine
      steps:
        - checkout
        - docker/pull:
            images: ubuntu:16.04,ubuntu:18.04
workflows:
  pull-images:
    jobs:
      - pull
```

### custom_readme_file

Build, deploy, and update the description of a Docker image with a non-standard description file


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          path: path/to/Docker/build/context
          readme: my.README.md
```

### custom_registry_and_dockerfile

Build and deploy a Docker image with a non-standard Dockerfile to a custom registry


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          dockerfile: my.Dockerfile
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          path: path/to/Docker/build/context
          registry: my.docker.registry
```

### hadolint

Use hadolint to lint a Dockerfile


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  lint:
    jobs:
      - docker/hadolint:
          dockerfiles: path/to/Dockerfile
          executor_class: medium
          hadolint_tag: 2.2.0-debian
          ignore_rules: DL4005,DL3008
          trusted_registries: docker.io,my-company.com:5000
```

### install_docker_tools

Quickly install Docker, docker-compose, and dockerize in any CircleCI job environment where they are missing


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
jobs:
  your-job:
    executor:
      name: docker/docker
      tag: '3.6'
    steps:
      - checkout
      - docker/install_docker_tools
workflows:
  your-workflow:
    jobs:
      - your-job
```

### lifecycle_hooks

Build and deploy a Docker image with custom lifecycle hooks: after checking out the code from the VCS repository, before building the Docker image, and after building the Docker image


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          after_build:
            - run:
                command: echo "Did this after the build"
                name: Do this after the build
          after_checkout:
            - run:
                command: echo "Did this after checkout"
                name: Do this after checkout
          before_build:
            - run:
                command: echo "Did this before the build"
                name: Do this before the build
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
```

### login_with_credentials_store

This demonstrates performing docker login with a credentials store configured, and then building an image with a Dockerfile in the root of your repository, naming the image to be the same name as your repository, and then pushing to the default docker registry (at docker.io)


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          use_docker_credentials_store: true
```

### standard_build_and_push

A standard Docker workflow, where you are building an image with a Dockerfile in the root of your repository, naming the image to be the same name as your repository, pushing to the default docker registry (at docker.io), and then updating the image description


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-and-publish-docker-image:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
```

### with_bash_substitution

Build/publish a Docker image bash substitution


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          image: ${CIRCLE_PROJECT_USERNAME,,}/${CIRCLE_PROJECT_REPONAME/_/-}
          tag: ${CIRCLE_SHA1:0:10}
```

### with_cache_from

Build/publish a Docker image using --cache-from


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          cache_from: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME:latest
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          tag: latest
```

### with_cache_to

Build/publish a Docker image using --cache-to


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          cache_to: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME:cache
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          tag: latest
```

### with_extra_build_args

Build/publish a Docker image with extra build arguments


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          extra_build_args: '--build-arg=FOO=bar --build-arg=BAZ=qux'
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
```

### with_multiple_tags

Build/publish a Docker image with extra build arguments


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          tag: tag1,tag2,tag3
```

### with_nested_dockerfile

Build/publish a Docker image building from a nested Dockerfile


```yaml
version: '2.1'
orbs:
  docker: circleci/docker@x.y.z
workflows:
  build-docker-image-only:
    jobs:
      - docker/publish:
          docker_context: .
          image: $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME
          path: dockerfiles/prod
```