Earthfile
, regardless of their location in the codebase.FROM <image-name>
FROM [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-key>=<build-arg-value>...]
FROM
command initializes a new build environment and sets the base image for subsequent instructions. It works similarly to the classical Dockerfile FROM
instruction, but it has the added ability to use another target's image as the base image.FROM alpine:latest
FROM +another-target
FROM ./subdirectory+some-target
FROM github.com/example/project+remote-target
FROM
command does not mark any saved images or artifacts of the referenced target for output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD
.FROM ... AS ...
form available in the classical Dockerfile syntax is not supported in Earthfiles. Instead, define a new Earthly target. For example, the following Dockerfile--<build-arg-key>=<build-arg-value>
<build-arg-value>
for the build arg identified by <build-arg-key>
. See also BUILD for more details about build args.--platform <platform>
--allow-privileged
--allow-privileged
(or -P
) flag.my-target
by invoking earthly with the --allow-privileged
(or -P
) flag:--build-arg <key>=<value>
(deprecated)--<build-arg-key>=<build-arg-value>
instead.RUN [--push] [--entrypoint] [--privileged] [--secret <env-var>=<secret-ref>] [--ssh] [--mount <mount-spec>] [--] <command>
(shell form)RUN [[<flags>...], "<executable>", "<arg1>", "<arg2>", ...]
(exec form)RUN
command executes commands in the build environment of the current target, in a new layer. It works similarly to the Dockerfile RUN
command, with some added options./bin/sh -c
) to interpret the command and execute it. In either form, you can use a \
to continue a single RUN
instruction onto the next line.--entrypoint
flag is used, the current image entrypoint is used to prepend the current command.RUN
flag option or part of the command, the delimiter --
may be used to signal the parser that no more RUN
flag options will follow.--push
--push
flag to the earthly
invocation to enable pushing. For example--no-cache
RUN --no-cache
, will also ignore the cache. If --no-cache
is used as an option on the RUN
statement within a WITH DOCKER
statement, all commands after the WITH DOCKER
will also ignore the cache.--entrypoint
docker run
in a traditional build environment. For example, a command like--privileged
--allow-privileged
(or -P
) to the earthly
command. Example:--secret <env-var>=<secret-ref> | <secret-id>
<env-var>
), to the command being executed. If you only specify <secret-id>
, the name of the env var will be <secret-id>
and its value the value of <secret-id>
.<secret-ref>
needs to be of the form +secrets/<secret-id>
, where <secret-id>
is the identifier passed to the earthly
command when passing the secret: earthly --secret <secret-id>=<value>
.<secret-ref>
, allowing for optional secrets, should it need to be disabled.RUN --mount type=secret,id=+secret/secret-id,target=/path/of/secret
. See --mount
below.--ssh
SSH_AUTH_SOCK
.--mount <mount-spec>
<mount-spec>
is defined as a series of comma-separated list of key-values. The following keys are allowedtype
cache
, tmpfs
, and secret
are allowed.type=cache
target
target=/var/lib/data
id
target
file, only applicable for type=secret
.id=+secrets/password
RUN
command, even when its dependencies change:/root/.netrc
file can then be specified from the command line as:--interactive
/ --interactive-keep
SAVE IMAGE
commands. This also means that you cannot FROM
a target containing a RUN --interactive
.--interactive
target within the run.LOCALLY
-designated target.bash
to tweak an image by hand. Changes made will be included:COPY [options...] <src>... <dest>
(classical form)COPY [options...] <src-artifact>... <dest>
(artifact form)COPY [options...] (<src-artifact> --<build-arg-key>=<build-arg-value>...) <dest>
(artifact form with build args)COPY
allows copying of files and directories between different contexts.COPY
copies files and directories from the build context into the build environment - in this form, it works similarly to the Dockerfile COPY
command. In the artifact form, COPY
copies files or directories (also known as "artifacts" in this context) from the artifact environment of other build targets into the build environment of the current target. Either form allows the use of wildcards for the sources.<src-artifact>
is an artifact reference and is generally of the form <target-ref>/<artifact-path>
, where <target-ref>
is the reference to the target which needs to be built in order to yield the artifact and <artifact-path>
is the path within the artifact environment of the target, where the file or directory is located. The <artifact-path>
may also be a wildcard.COPY
command does not mark any saved images or artifacts of the referenced target for output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD
.COPY
command differs from Dockerfiles in two cases:/
.earthlyignore
file. This file has the same syntax as a .dockerignore
file.--dir
--dir
changes the behavior of the COPY
command to copy the directories themselves, rather than the contents of the directories. It allows the command to behave similarly to a cp -r
operation on a unix system. This allows the enumeration of several directories to be copied over on a single line (and thus, within a single layer). For example, the following two are equivalent with respect to what is being copied in the end (but not equivalent with respect to the number of layers used).--<build-arg-key>=<build-arg-value>
<build-arg-value>
for the build arg identified by <build-arg-key>
, when building the target containing the mentioned artifact. See also BUILD for more details about the build arg options.--keep-ts
--keep-own
--if-exists
--from
SAVE ARTIFACT
and COPY
artifact form commands to achieve similar effects. For example, the following Dockerfilefinal-target
in the following Earthfile--platform <platform>
--allow-privileged
--build-arg <key>=<value>
(deprecated)--build-arg
is deprecated. Use --<build-arg-key>=<build-arg-value>
instead.test
:ARG [--required] <name>[=<default-value>]
(constant form)ARG [--required] <name>=$(<default-value-expr>)
(dynamic form)ARG
declares a variable (or arg) with the name <name>
and with an optional default value <default-value>
. If no default value is provided, then empty string is used as the default value.ARG
command, with a few differences regarding the scope and the predefined args (called builtin args in Earthly). The variable's scope is always limited to the recipe of the current target or command and only from the point it is declared onward. For more information regarding builtin args, see the builtin args page.<default-value>
is not provided, then the default value is an empty string. In its dynamic form, the arg takes a default value defined as an expression. The expression is evaluated at run time and its result is used as the default value. The expression is interpreted via the default shell (/bin/sh -c
) within the build environment.ARG
is defined in the base
target of the Earthfile, then it becomes a global ARG
and it is made available to every other target or command in that file, regardless of their base images used.earthly
commandARG
--required
ARG
must be provided at build time and can never have a default value. Required args can help eliminate cases where the user has unexpectedly set an ARG
to ""
.$(...)
shell-out syntax -- passing a value such as --name="the honourable $(whoami)"
will fail to execute the whoami
program.VERSION
--shell-out-anywhere
feature flag. This feature additionally allows shelling-out in any earthly command.SAVE ARTIFACT [--keep-ts] [--keep-own] [--if-exists] [--force] <src> [<artifact-dest-path>] [AS LOCAL <local-path>]
SAVE ARTIFACT
copies a file, a directory, or a series of files and directories represented by a wildcard, from the build environment into the target's artifact environment.AS LOCAL ...
is also specified, it additionally marks the artifact to be copied to the host at the location specified by <local-path>
, once the build is deemed as successful.<artifact-dest-path>
is not specified, it is inferred as /
.COPY
command), using an artifact reference.+<target>
into a local directory called output
, which can be inspected directly.--keep-ts
--keep-own
--if-exists
--force
test
:SAVE ARTIFACT ... AS LOCAL
commands will behave:SAVE IMAGE [--cache-from=<cache-image>] [--push] <image-name>...
(output form)SAVE IMAGE --cache-hint
(cache hint form)SAVE IMAGE
marks the current build environment as the image of the target and assigns an output image name.--push
--push
options marks the image to be pushed to an external registry after it has been loaded within the docker daemon available on the host.--push
option also instructs Earthly to use the specified image names as cache sources.--push
flag to the earthly invocation to enable pushing. For example--cache-from=<cache-image>
--use-inline-cache
is enabled. For more information see the shared caching guide.--cache-hint
BUILD [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-name>=<build-arg-value>...]
BUILD
instructs Earthly to additionally invoke the build of the target referenced by <target-ref>
, where <target-ref>
follows the rules defined by target referencing. The invocation will mark any images, or artifacts saved by the referenced target for local output (assuming local output is enabled), and any push commands issued by the referenced target for pushing (assuming pushing is enabled).BUILD
calls. Other ways to reference a target, such as FROM
, COPY
, WITH DOCKER --load
etc, do not contribute to the final set of outputs or pushes.COPY
and you would like for the outputs or pushes to be included, you can issue an equivalent BUILD
command in addition to the COPY
. For exampleBUILD
call:+my-target
is itself connected via a BUILD
chain to the main target being built. If that is not the case, additional BUILD
commands should be issued higher up the hierarchy.--<build-arg-key>=<build-arg-value>
<build-arg-value>
for the build arg identified by <build-arg-key>
.$(...)
.--platform <platform>
--allow-privileged
--build-arg <build-arg-key>=<build-arg-value>
(deprecated)--<build-arg-key>=<build-arg-value>
instead.VERSION [options...] <version-number>
VERSION
identifies which set of features to enable in Earthly while handling the corresponding Earthfile. The VERSION
command is currently optional; however will become mandatory in a future version of Earthly. When specified, VERSION
must be the first command in the Earthfile.0.5
0.6
--use-copy-include-patterns --referenced-save-only --for-in --require-force-for-unsafe-saves --no-implicit-ignore
GIT CLONE [--branch <git-ref>] [--keep-ts] <git-url> <dest-path>
GIT CLONE
clones a git repository from <git-url>
, optionally referenced by <git-ref>
, into the build environment, within the <dest-path>
.RUN git clone <git-url> <dest-path>
, the command GIT CLONE
is cache-aware and correctly distinguishes between different git commit IDs when deciding to reuse a previous cache or not. In addition, GIT CLONE
can also use Git authentication configuration passed on to earthly
, whereas RUN git clone
would require additional secrets passing, if the repository is not publicly accessible.--branch <git-ref>
HEAD
to the git reference specified by <git-ref>
. If this option is not specified, then the remote HEAD
is used instead.--keep-ts
FROM DOCKERFILE [options...] <context-path>
FROM DOCKERFILE
command initializes a new build environment, inheriting from an existing Dockerfile. This allows the use of Dockerfiles in Earthly builds.<context-path>
is the path where the Dockerfile build context exists. By default, it is assumed that a file named Dockerfile
exists in that directory. The context path can be either a path on the host system, or an artifact reference, pointing to a directory containing a Dockerfile
.-f <dockerfile-path>
<dockerfile-path>
can be either a path on the host system, relative to the current Earthfile, or an artifact reference pointing to a Dockerfile.Dockerfile
and the build context across two seperate artifact references:+mybuildcontext/mydata
on its own would copy the directory and its contents; where as +mybuildcontext/mydata/*
is required to copy all of the contents from within the mydata
directory ( without copying the wrapping mydata
directory).Dockerfile
and build context are inside the same target, one must reference the same target twice, e.g. FROM DOCKERFILE -f +target/dir/Dockerfile +target/dir
.--build-arg <key>=<value>
<value>
for the Dockerfile build arg identified by <key>
. This option is similar to the docker build --build-arg <key>=<value>
option.--target <target-name>
docker build --target <target-name>
option.--platform <platform>
WITH DOCKER
initializes a Docker daemon to be used in the context of a RUN
command. The Docker daemon can be pre-loaded with a set of images using options such as -pull
and --load
. Once the execution of the RUN
command has completed, the Docker daemon is stopped and all of its data is deleted, including any volumes and network configuration. Any other files that may have been created are kept, however.WITH DOCKER
automatically implies the RUN --privileged
flag.WITH DOCKER
clause only supports the command RUN
. Other commands (such as COPY
) need to be run either before or after WITH DOCKER ... END
. In addition, only one RUN
command is permitted within WITH DOCKER
. However, multiple shell commands may be stringed together using ;
or &&
.WITH DOCKER
clause might be:dockerd
. If dockerd
is not found, Earthly will attempt to install it.earthly/dind:alpine
and earthly/dind:ubuntu
to be used together with WITH DOCKER
.--pull <image-name>
<image-name>
from a remote registry and then loads it into the temporary Docker daemon created by WITH DOCKER
.RUN docker pull ...
and use WITH DOCKER --pull ...
instead. The classical docker pull
command does not take into account Earthly caching and so it would redownload the image much more frequently than necessary.--load <image-name>=<target-ref>
<target-ref>
and then loads it into the temporary Docker daemon created by WITH DOCKER
. The image can be referenced as <image-name>
within WITH DOCKER
.<target-ref>
may be a simple target reference (+some-target
), or a target reference with a build arg (+some-target --SOME_BUILD_ARG=value)
.WITH DOCKER --load
option does not mark any saved images or artifacts of the referenced target for local output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD
.--compose <compose-file>
<compose-file>
, adds all applicable images to the pull list and starts up all applicable compose services within.-f
flag in the docker-compose
command.--service <compose-service>
--compose
is used, then all services are pulled and started up.--compose
has been specified.--platform <platform>
--load
and --pull
images.--allow-privileged
--build-arg <key>=<value>
(deprecated)--load <image-name>=(<target-ref> --<build-arg-key>=<build-arg-value>)
instead.IF
clause can perform varying commands depending on the outcome of one or more conditions. The expression passed as part of <condition>
is evaluated by running it in the build environment. If the exit code of the expression is zero, then the block of that condition is executed. Otherwise, the control continues to the next ELSE IF
condition (if any), or if no condition returns a non-zero exit code, the control continues to executing the <else-block>
, if one is provided.[ ... ]
conditions. For example the following marks port 8080
as exposed if the file ./foo
exists.FROM
(or a from-like command, such as LOCALLY
) has been issued before the condition itself.IF
condition is actually running the /usr/bin/[
executable to test if the condition is true or false, and therefore requires that a valid build environment has been initialized.FROM busybox
, the IF
condition can execute on top of the busybox
image.--privileged
--ssh
--no-cache
--mount <mount-spec>
--secret <env-var>=<secret-ref>
VERSION 0.6
.FOR
clause can iterate over the items resulting from the expression <expression>
. On each iteration, the value of <variable-name>
is set to the current item in the iteration and the block of commands <for-block>
is executed in the context of that variable set as a build arg.foo bar buz
), or the output of a command (e.g. $(echo foo bar buz)
), or a parameterized list of items (e.g. foo $BARBUZ
). The result of the expression is then tokenized using the list of separators provided via the --sep
option. If unspecified, the separator list defaults to [tab]
, [new line]
and [space]
(\t\n
).FOR
expression, then that file will not be present in the build environment for any subsequent commands.FOR
may be used to iterate over a list of files for compilationFOR
may be used to iterate over a set of directories in a monorepo and invoking targets within them.--sep <separator-list>
[tab]
, [new line]
and [space]
(\t\n
).--privileged
--ssh
--no-cache
--mount <mount-spec>
--secret <env-var>=<secret-ref>
LOCALLY
LOCALLY
command can be used in place of a FROM
command, which will cause earthly to execute all commands under the target directly on the host system, rather than inside a container. Commands within a LOCALLY
target will never be cached. This feature should be used with caution as locally run commands have no guarantee they will behave the same on different systems.RUN
commands are supported under a LOCALLY
defined target; furthermore only RUN
's --push
flag is supported.RUN
commands have access to the environment variables which are exposed to the earthly
command; however, the commands are executed within a working directory which is set to the location of the referenced Earthfile and not where the earthly
command is run from.LOCALLY
targets, they need to be referenced correctly.--load
option under WITH DOCKER
:BUILD
for using images in LOCALLY
targets:COPY
, the same way you would in a regular target:SAVE ARTIFACT ... AS LOCAL
and BUILD
for referencing artifacts in LOCALLY
targets:COMMAND
COMMAND
marks the beginning of a user-defined command (UDC) definition. UDCs are templates (much like functions in regular programming languages), which can be used to define a series of steps to be executed in sequence. In order to reference and execute a UDC, you may use the command DO
.BUILD +target
, UDCs inherit the build context and the build environment from the caller.ARG
scope, which is distinct from the caller. Any ARG
that needs to be passed from the caller needs to be passed explicitly via DO +COMMAND --<build-arg-key>=<build-arg-value>
.base
target of the same Earthfile where the command is defined in (this may be distinct from the base
target of the caller).DO [--allow-privileged] <command-ref> [--<build-arg-key>=<build-arg-value>...]
DO
expands and executes the series of commands contained within a user-defined command (UDC) referenced by <command-ref>
.BUILD +target
, UDCs inherit the build context and the build environment from the caller.ARG
scope, which is distinct from the caller. Any ARG
that needs to be passed from the caller needs to be passed explicitly via DO +COMMAND --<build-arg-key>=<build-arg-value>
.--allow-privileged
IMPORT [--allow-privileged] <project-ref> [AS <alias>]
IMPORT
aliases a project reference (<project-ref>
) that can be used in subsequent target, artifact or command references.<alias>
is inferred automatically as the last element of the path provided in <project-ref>
. For example, if <project-ref>
is github.com/foo/bar/buz:v1.2.3
, then the alias is inferred as buz
.<project-ref>
can be a reference to any directory other than .
. If the reference ends in ..
, then mentioning AS <alias>
is mandatory.IMPORT
is defined in the base
target of the Earthfile, then it becomes a global IMPORT
and it is made available to every other target or command in that file, regardless of their base images used.--allow-privileged
FROM --allow-privileged
, extend the ability to request privileged capabilities to all invocations of the imported alias.CMD ["executable", "arg1", "arg2"]
(exec form)CMD ["arg1, "arg2"]
(as default arguments to the entrypoint)CMD command arg1 arg2
(shell form)CMD
sets default arguments for an image, when executing as a container. It works the same way as the Dockerfile CMD
command.LABEL <key>=<value> <key>=<value> ...