Docker Layer Caching

Docker layer caching reuses the intermediate layers produced by docker build (the result of each RUN, COPY, and ADD instruction) across CI runs. When a layer's inputs haven't changed, the build pulls it from a registry cache instead of rebuilding it, cutting image build times on Nx Agents.

How to enable it

Requires a dedicated compute cluster

Docker layer caching is an Nx Cloud add-on that runs on a dedicated compute cluster. Request the cluster, then enable this add-on under Settings > Add-ons.

You can enable Docker layer caching through your organization settings:

1. Open Settings > Add-ons for your organization.
2. Under Dedicated compute cluster card, find Docker layer caching and click Request add-on and confirm.

When the add-on is enabled, Nx Cloud runs a registry cache inside your dedicated cluster and injects its address into every agent as the NX_DOCKER_CACHE_REGISTRY environment variable. You point your Docker builds at that registry using BuildKit's --cache-to and --cache-from flags. Cached layers are written to and read from the in-cluster registry, so they persist across CI runs.

Setup

1. Set up Docker Buildx

Layer caching requires BuildKit. Add the Buildx setup step to the init-steps of the launch template that runs your Docker builds, so it runs before any docker build command:

- name: Setup Docker Buildx
  uses: 'nrwl/nx-cloud-workflows/main/workflow-steps/setup-docker-buildx/main.yaml'

2. Add cache flags to your build commands

Update your docker build commands to export and import layers from the cache registry:

docker build \
  --push \
  -t my-registry.example.com/my-app:1.2.3 \
  --cache-to type=registry,ref=${NX_DOCKER_CACHE_REGISTRY}/my-app:main,mode=max \
  --cache-from type=registry,ref=${NX_DOCKER_CACHE_REGISTRY}/my-app:main \
  .

• -t my-registry.example.com/my-app:1.2.3 - your image, tag, and destination registry. Your agents must be authenticated to that registry to push images. That setup is outside the scope of this guide.
• ${NX_DOCKER_CACHE_REGISTRY} - provided by Nx Cloud. It points at the in-cluster cache registry, which is separate from your final image registry. Don't push your application images there.
• /my-app:main - the cache reference and tag. Use the main tag so subsequent builds reuse the cached layers.
• --cache-to mode=max - exports all layers for maximum reuse. mode=min exports fewer layers; see the Docker registry cache docs.
• --cache-from - imports cached layers when available.

Use stable cache image

Use the stable tag main for --cache-to and --cache-from. Layers stored under the main tag are kept permanently. Other tags are removed periodically, so non-main tags won't persist as long-lived cache.

Use distinct names per cache image (e.g. my-app:main and my-api:main) so different builds don't overwrite each other's layers.

See the Docker registry cache docs for more details.

3. Verify it's working

After the cache is warm, subsequent builds should show:

• [CACHED] markers in the docker build logs where layers were reused.
• Shorter build times for unchanged layers.