earthly/buildkitd
This image contains buildkit
with 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.
Tags
Currently, the latest
tag is v0.8.13
.
For other available tags, please check out https://hub.docker.com/r/earthly/buildkitd/tags
Quickstart
Want to just get started? Here are a couple sample docker run
commands that cover the most common use-cases:
Simple Usage (Use Locally)
Heres a quick breakdown:
--privileged
is required. This is becauseearthly
needs some privilegedbuildkit
functionality.-t
tells Docker to emulate a TTY. This makes thebuildkit
log output colorized.-v earthly-tmp:/tmp/earthly:rw
mounts (and creates, if necessary) theearthly-tmp
Docker volume into the containers/tmp/earthly
. This is used as a temporary/working directory forbuildkitd
during builds.
Assuming you are running this on your machine, you could use this buildkitd
by setting EARTHLY_BUILDKIT_HOST=docker-container://<container-name>
, or by specifying the appropriate values in config.yml
.
Usage (Use As Remote)
Omitting the options already discussed from the simple example:
-e BUILDKIT_TCP_TRANSPORT_ENABLED=true
makesbuildkitd
listen on a TCP port instead of a Unix socket.-p 8372:8372
forwards the hosts port 8372 to the containers port 8372. When using TCP,buildkit
will 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 buildkitd
by setting EARTHLY_BUILDKIT_HOST=tcp://fast-builder:8372
, or by specifying the address in your config.yml
.
Using This Image
Requirements
Privileged Mode
This image needs to be run as a privileged container. This is because buildkitd
needs appropriate access to start and run additional containers itself via runc
.
/tmp/earthly
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, buildkitd
can consume excessive disk space, operate very slowly, or it might not function correctly.
In some environments, not mounting /tmp/earthly
as a Docker volume results in the following error:
External Usage
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_HOST
values with hosts 127.0.0.1
, ::1/128
, or localhost
are 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.
Supported Environment Variables
Variable Name | Default Values | Description |
---|---|---|
EARTHLY_ADDITIONAL_BUILDKIT_CONFIG | Additional | |
BUILDKIT_TCP_TRANSPORT_ENABLED | Set to | |
BUILDKIT_TLS_ENABLED | Set to | |
CNI_MTU | MTU of first default interface | Set this when we autodetect the MTU incorrectly. The device used for autodetection can be shown by the command |
EARTHLY_RESET_TMP_DIR |
| Cleans out |
NETWORK_MODE |
| Specifies the networking mode of |
CACHE_SIZE_MB |
| How big should the |
GIT_URL_INSTEAD_OF | Configure | |
IP_TABLES | Override which binary ( |
Last updated