docker:cache

Docker Cache, builds a Docker image as a cache for reuse in subsequent builds.

It helps avoid redundant downloads of network resources such as dependencies.

• Applicable Events
• Parameters
• Output Results
• Configuration Examples

Applicable Events

All Events

Parameters

The list below gives an overview of all parameters before you jump to a specific section for details.

• dockerfile: Dockerfile path used to build the cache image
• by: Files the cache image build depends on; used to trigger a cache rebuild
• versionBy: Files involved in cache version calculation; defaults to by
• buildArgs: Extra --build-arg arguments injected at build time
• target: Maps to docker build --target; build only a specific stage
• sync: Sync mode; wait until the cache image push succeeds before continuing
• ignoreBuildArgsInVersion: Whether to ignore buildArgs in version calculation

Detailed descriptions for each parameter are provided below.

dockerfile

• type: String
• required: true

The path to the Dockerfile used to build the cache image.

To avoid excessively long build times, the Docker image build timeout is controlled by the job.timeout parameter.

by

• type: Array<String> | String
• required: false

Specifies the list of files that the cache image build process depends on.

The Docker build context (the files visible during docker build) contains only the Dockerfile and the files declared in by. If the cache image build also needs other files, list them in by as well; otherwise they are not copied into the build context and are effectively unavailable during the build.

• Supports array format
• Supports string format, with multiple files separated by commas.

versionBy

• type: Array<String> | String
• required: false

Used for version control. If versionBy is not provided, it defaults to the value of by.

When the content of the file pointed to by versionBy changes, a new version is considered. The calculation logic is based on the expression:

sha1(Dockerfile + versionBy + buildArgs + target + arch)

• Supports array format
• Supports string format, with multiple files separated by commas.

buildArgs

• type: Object
• required: false

Inserts additional build arguments during build (--build-arg $key=$value). If the value is null, only the key is added (--build-arg $key).

target

• type: String
• required: false

Corresponds to the --target parameter in docker build, allowing selective building of specific stages in the Dockerfile instead of the entire Dockerfile.

sync

• type: Boolean
• required: false
• default: false

Specifies whether to operate in synchronous mode. If true, it waits for the cache image to be successfully pushed before proceeding with subsequent tasks.

ignoreBuildArgsInVersion

• type: Boolean
• required: false
• default: false

Specifies whether to ignore buildArgs in version calculation.

See Version Control

Output Results

{
  // The docker image name corresponding to the cache
  name;
}

Configuration Examples

.cnb.yml

main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            # by supports two formats: array, string
            by:
              - package.json
              - package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: build with cache
          script:
            - npm run build

Where cache.dockerfile is a Dockerfile used to build the cache image, for example:

# Choose a Base image
FROM node:14

# Set working directory
WORKDIR /space

# Copy the file list from 'by'
COPY . .

# Install dependencies based on the copied files
RUN npm ci

# Set the required environment variables
ENV NODE_PATH=/space/node_modules