This image contains
buildkitwith some Earthly-specific setup. This is what Earthly will start when using a local daemon. You can also start it up yourself and use it as a remote/shared BuildKit daemon.
Note that versions of this container have only ever been tested with their corresponding version of
earthly. Mismatched versions are unsupported.
Want to just get started? Here are a couple sample
docker runcommands that cover the most common use-cases:
docker run --privileged -t -v earthly-tmp:/tmp/earthly:rw earthly/buildkitd:v0.6.30
Heres a quick breakdown:
--privilegedis required. This is because
earthlyneeds some privileged
-ttells Docker to emulate a TTY. This makes the
buildkitlog output colorized.
-v earthly-tmp:/tmp/earthly:rwmounts (and creates, if necessary) the
earthly-tmpDocker volume into the containers
/tmp/earthly. This is used as a temporary/working directory for
Assuming you are running this on your machine, you could use this
EARTHLY_BUILDKIT_HOST=docker-container://<container-name>, or by specifying the appropriate values in
docker run --privileged -t -v earthly-tmp:/tmp/earthly:rw -e BUILDKIT_TCP_TRANSPORT_ENABLED=true -p 8372:8372 earthly/buildkitd:v0.6.30
Omitting the options already discussed from the simple example:
buildkitdlisten on a TCP port instead of a Unix socket.
-p 8372:8372forwards the hosts port 8372 to the containers port 8372. When using TCP,
buildkitwill always listen on 8372, but you can configure the apparent port by forwarding a different port on your host.
Assuming you ran this on another machine named
fast-builder, you could use this remote
EARTHLY_BUILDKIT_HOST=tcp://fast-builder:8372, or by specifying the address in your
This image needs to be run as a privileged container. This is because
buildkitdneeds appropriate access to start and run additional containers itself via
Because this folder sees a lot of traffic, its important that it remains fast. We strongly recommend using a Docker volume for mounting
/tmp/earthly. If you do not,
buildkitdcan consume excessive disk space, operate very slowly, or it might not function correctly.
In some environments, not mounting
/tmp/earthlyas a Docker volume results in the following error:
--> WITH DOCKER RUN --privileged ...
rm: can't remove '/var/earthly/dind/...': Resource busy
To use this image externally, it requires you to forward a port on your machine to the containers port 8372. You will need to ensure that external access to the machine on the port you chose is possible as well.
When using this container locally with
earthly, please note that setting
EARTHLY_BUILDKIT_HOSTvalues with hosts
localhostare considered local and will result in Earthly attempting to manage the BuildKit container itself. Consider using your hostname, or another alternative name in these cases.