diff --git a/docs/manuals/drivers/docker-container.md b/docs/manuals/drivers/docker-container.md index be45bf47..eebf74b2 100644 --- a/docs/manuals/drivers/docker-container.md +++ b/docs/manuals/drivers/docker-container.md @@ -78,7 +78,42 @@ REPOSITORY TAG IMAGE ID CREATED latest adf3eec768a1 2 minutes ago 197MB ``` -### QEMU +## Cache persistence + +The `docker-container` driver supports cache persistence, as it stores all of +the BuildKit state and related cache into a dedicated docker volume. + +To persist the `docker-container` driver's cache, even after recreating the +driver using `docker buildx rm` and `docker buildx create`, you can destroy the +builder using the `--keep-state` flag: + +For example, to create a builder named `container` and then remove it while +persisting state: + +```console +# setup a builder +$ docker buildx create --name=container --driver=docker-container --use --bootstrap +container +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS +container * docker-container + container0 desktop-linux running v0.10.5 linux/amd64 +$ docker volume ls +DRIVER VOLUME NAME +local buildx_buildkit_container0_state + +# remove the builder while persisting state +$ docker buildx rm --keep-state container +$ docker volume ls +DRIVER VOLUME NAME +local buildx_buildkit_container0_state + +# the newly created driver with the same name will have all the state of the previous one! +$ docker buildx create --name=container --driver=docker-container --use --bootstrap +container +``` + +## QEMU The `docker-container` driver supports using [QEMU](https://www.qemu.org/) (user mode) to build non-native platforms. Use the `--platform` flag to specify which