Sign in

BuildKit Reference

Clipper has a BuildKit build driver with several advantages over the default driver. For a quick setup guide with GHA, see CI/CD Integration.

Driver image: clipperregistry/buildkit:latest.

Local

Create the Clipper driver, set as default.

docker buildx create --driver-opt image=clipperregistry/buildkit:latest --use

or create the driver, use on demand

docker buildx create --driver-opt image=clipperregistry/buildkit:latest --name clipper
docker buildx build --driver clipper ...

GHA

      - uses: docker/setup-buildx-action@v4
        with:
          driver-opts: image=clipperregistry/buildkit:latest

Clipper Export

Required for build output to clipper.dev

A docker buildx build --output type that writes the build result in Clipper’s format.

OptionTypeDefaultDescription
namestringrequiredTarget reference, e.g. clipper.dev/myorg/myapp:1.0.
pushbooltruePush to the registry. When false, the result stays in the local content store.

Example

--output type=clipper,name=clipper.dev/myorg/myapp:1.0

Cache Export

Automatic, using the Clipper build driver, cache mount will be exported in Clipper’s format.

Cache Mount Export

Allows for pushing/pulling RUN --mount=type=cache directories to Clipper. A value for the mode attribute on --cache-to / --cache-from. This is independent of the layer cache, use a separate cache ref for each (eg cache and cache-mounts). Cache mounts always use lazy pulling, to allow building a large cache without wasting time pulling unused files.

Supported on all standard cache backends:

Backend--cache-to--cache-from
registrytype=registry,ref=<ref>,mode=cache-mounttype=registry,ref=<ref>,mode=cache-mount
ghatype=gha,scope=<scope>,mode=cache-mount,repository=<repo>,ghtoken=<token>type=gha,scope=<scope>,mode=cache-mount
localtype=local,dest=<path>,mode=cache-mounttype=local,src=<path>,mode=cache-mount

Example

  docker buildx build \
    --output      type=clipper,name=clipper.dev/myorg/myapp:1.0 \
    --cache-to    type=registry,ref=clipper.dev/myorg/myapp-cache:main,mode=max \
    --cache-from  type=registry,ref=clipper.dev/myorg/myapp-cache:main \
    --cache-to    type=registry,ref=clipper.dev/myorg/myapp-cache:main-mounts,mode=cache-mount \
    --cache-from  type=registry,ref=clipper.dev/myorg/myapp-cache:main-mounts,mode=cache-mount \
    .

Lazy pulls: the clipper-lazy snapshotter

An OCI worker snapshotter that serves files from Clipper base images (FROM clipper.dev/...) and cached layers on demand instead of downloading and extracting every layer before the build starts. Only the files a build step actually reads are fetched, which can speed up pulls on large images. Linux only.

While lazy pulling is generally faster, your mileage may vary - profile after enabling.

Enable it in the buildkitd config:

[worker.oci]
  snapshotter = "clipper-lazy"

With setup-buildx-action, pass that config inline:

      - uses: docker/setup-buildx-action@v4
        with:
          driver-opts: image=clipperregistry/buildkit:latest
          buildkitd-config-inline: |
            [worker.oci]
              snapshotter = "clipper-lazy"