Earthfile reference

Earthfiles are comprised of a series of target declarations and recipe definitions. Earthfiles are named Earthfile, regardless of their location in the codebase. For backwards compatibility, the name build.earth is also permitted. This compatibility will be removed in a future version.

Earthfiles have the following rough structure:

...
base recipe
...
target:
...
recipe
...
target:
...
recipe
...

Each recipe contains a series of commands, which are defined below. For an introduction into Earthfiles, see the Basics page.

FROM

Synopsis

  • FROM <image-name>

  • FROM [--build-arg <key>=<value>] <target-ref>

Description

The 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 for the build. For example: FROM +another-target.

Note

The 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

# Dockerfile
FROM alpine:3.11 AS build
# ... instructions for build
FROM build as another
# ... further instructions inheriting build
FROM busybox as yet-another
COPY --from=build ./a-file ./

can become

# Earthfile
build:
FROM alpine:3.11
# ... instructions for build
SAVE ARTIFACT ./a-file
SAVE IMAGE
another:
FROM +build
# ... further instructions inheriting build
yet-another:
FROM busybox
COPY +build/a-file ./

Options

--build-arg <key>=<value>

Sets a value override of <value> for the build arg identified by <key>. See also BUILD for more details about the --build-arg option.

RUN

Synopsis

  • RUN [--push] [--entrypoint] [--privileged] [--with-docker] [--secret <env-var>=<secret-ref>] [--mount <mount-spec>] [--] <command> (shell form)

  • RUN [[<flags>...], "<executable>", "<arg1>", "<arg2>", ...] (exec form)

Description

The 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.

The command allows for two possible forms. The exec form runs the command executable without the use of a shell. The shell form uses the default shell (/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.

When the --entrypoint flag is used, the current image entrypoint is used to prepend the current command.

To avoid any ambiguity regarding whether an argument is a 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.

Options

--push

Marks the command as a "push command". Push commands are only executed if all other non-push instructions succeed. In addition, push commands are never cached, thus they are executed on every applicable invocation of the build.

Push commands are not run by default. Add the --push flag to the earth invocation to enable pushing. For example

earth --push +deploy

Push commands were introduced to allow the user to define commands that have an effect external to the build. This kind of effects are only allowed to take place if the entire build succeeds. Good candidates for push commands are uploads of artifacts to artifactories, commands that make a change to an external environment, like a production or staging environment.

Note that non-push commands are not allowed to follow a push command within a recipe.

--entrypoint

Prepends the currently defined entrypoint to the command.

This option is useful for replacing docker run in a traditional build environment. For example, a command like

docker run --rm -v "$(pwd):/data" cytopia/golint .

Might become the following in an Earthfile

FROM cytopia/goling
COPY . /data
RUN --entrypoint .

--privileged

Allows the command to use privileged capabilities.

Note that privileged mode is not enabled by default. In order to use this option, you need to additionally pass the flag --allow-privileged (or -P) to the earth command. Example:

earth --allow-privileged +some-target

--with-docker [experimental]

RUN --with-docker is experimental and is subject to change.

Makes available a docker daemon within the build environment, which the command can leverage. This option automatically implies --privileged.

Example:

RUN --with-docker docker run hello-world

or

RUN --with-docker docker-compose up -d ; docker run some-test-image

--secret <env-var>=<secret-ref>

Makes available a secret, in the form of an env var (its name is defined by <env-var>), to the command being executed.

The <secret-ref> needs to be of the form +secrets/<secret-id>, where <secret-id> is the identifier passed to the earth command when passing the secret: earth --secret <secret-id>=<value>.

Here is an example:

release:
RUN --push --secret GITHUB_TOKEN=+secrets/GH_TOKEN github-release upload
earth --secret GH_TOKEN="the-actual-secret-token-value" +release

--mount <mount-spec>

Mounts a file or directory in the context of the build environment.

The <mount-spec> is defined as a series of comma-separated list of key-values. The following keys are allowed

Key

Description

Example

type

The type of the mount. Currently only cache is allowed.

type=cache

target

The target path for the mount.

target=/var/lib/data

Example:

ENV GOCACHE=/go-cache
RUN --mount=type=cache,target=/go-cache go build main.go

Note that mounts cannot be shared between targets, nor can they be shared within the same target, if the build-args differ between invocations.

COPY

Synopsis

  • COPY [--dir] <src>... <dest> (classical form)

  • COPY [--dir] [--build-arg <key>=<value>] <src-artifact>... <dest> (artifact form)

Description

The command COPY allows copying of files and directories between different contexts.

The command may take a couple of possible forms. In the classical form, 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.

The parameter <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.

Note that the Dockerfile form of COPY whereby you can reference a source as a URL is not yet supported in Earthfiles.

Options

--dir

The option --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).

COPY dir1 dir1
COPY dir2 dir2
COPY dir3 dir3
COPY --dir dir1 dir2 dir3 ./

--build-arg <key>=<value>

Sets a value override of <value> for the build arg identified by <key>, when building the target containing the mentioned artifact. See also BUILD for more details about the --build-arg option.

--from

Although this option is present in classical Dockerfile syntax, it is not supported by Earthfiles. You may instead use a combination of SAVE ARTIFACT and COPY artifact form commands to achieve similar effects. For example, the following Dockerfile

# Dockerfile
COPY --from=some-image /path/to/some-file.txt ./

... would be equivalent to final-target in the following Earthfile

# Earthfile
intermediate:
FROM some-image
SAVE ARTIFACT /path/to/some-file.txt
final-target:
COPY +intermediate/some-file.txt ./

GIT CLONE

Synopsis

  • GIT CLONE [--branch <git-ref>] <git-url> <dest-path>

Description

The command GIT CLONE clones a git repository from <git-url>, optionally referenced by <git-ref>, into the build environment, within the <dest-path>.

In contrast to an operation like 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 earth, whereas RUN git clone would require additional secrets passing, if the repository is not publicly accessible.

Options

--branch <git-ref>

Points the HEAD to the git reference specified by <git-ref>. If this option is not specified, then the remote HEAD is used instead.

SAVE ARTIFACT

Synopsis

  • SAVE ARTIFACT <src> [<artifact-dest-path>] [AS LOCAL <local-path>]

Description

The command 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.

If 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.

If <artifact-dest-path> is not specified, it is inferred as /.

Files within the artifact environment are also known as "artifacts". Once a file has been copied into the artifact environment, it can be referenced in other places of the build (for example in a COPY command), using an artifact reference.

SAVE IMAGE

Synopsis

  • SAVE IMAGE [[--push] <image-name>...]

Description

The command SAVE IMAGE marks the current build environment as the image of the target. The image can then be referenced using an image reference in other parts of the build (for example in a FROM command).

If one ore more <image-name>'s are specified, the command also marks the image to be loaded within the docker daemon available on the host.

Note

It is an error to issue the command SAVE IMAGE twice within the same recipe. In addition, the SAVE IMAGE command is always implied at the end of the base target, thus issuing SAVE IMAGE within the recipe of the base target is also an error.

Options

--push

The --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 commands are not run by default. Add the --push flag to the earth invocation to enable pushing. For example

earth --push +docker-image

BUILD

Synopsis

  • BUILD [--build-arg <key>=<value>] <target-ref>

Description

The command 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.

Options

--build-arg <key>=<value>

Sets a value override of <value> for the build arg identified by <key>.

The override value of a build arg may be a constant string

--build-arg SOME_ARG="a constant value"

or an expression involving other build args

--build-arg SOME_ARG="a value based on other args, like $ANOTHER_ARG and $YET_ANOTHER_ARG"

or a dynamic expression, based on the output of a command executed in the context of the build environment. In this case, the build arg becomes a "variable build arg".

--build-arg SOME_ARG=$(find /app -type f -name '*.php')

ARG

Synopsis

  • ARG <name>[=<default-value>]

Description

The command 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.

This command works similarly to the Dockerfile 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 current target's recipe and only from the point it is declared onwards. For more information regarding builtin args, see the builtin args page.

The value of an arg can be overridden either from the earth command

earth --build-arg <name>=<override-value>

or from a command from another target, when implicitly or explicitly invoking the target containing the ARG

BUILD --build-arg <name>=<override-value> <target-ref>
COPY --build-arg <name>=<override-value> <target-ref>/<artifact-path>... <dest-path>
FROM --build-arg <name>=<override-value> <target-ref>

for example

BUILD --build-arg PLATFORM=linux +binary
COPY --build-arg PLATFORM=linux +binary/bin ./
FROM --build-arg NAME=john +docker-image

A number of builtin args are available and are pre-filled by Earthly. For more information see builtin args.

DOCKER PULL [experimental]

DOCKER PULL is experimental and is subject to change.

Synopsis

  • DOCKER PULL <image-name>

Description

The command DOCKER PULL pulls a docker image from a remote registry into the docker daemon available within the build envionment. It can be used in conjunction with RUN --with-docker docker run ... to execute docker images in the context of the build environment.

DOCKER LOAD [experimental]

DOCKER LOAD is experimental and is subject to change.

Synopsis

  • DOCKER LOAD [--build-arg <name>=<override-value>] <target-ref> AS <image-name>

Description

The command DOCKER LOAD builds the image referenced by <target-ref> and then loads it into the docker daemon available within the build environment, as a docker image <image-name>. It can be used in conjunction with RUN --with-docker docker run ... to execute docker images that are produced by other targets of the build.

Options

--build-arg <key>=<value>

Sets a value override of <value> for the build arg identified by <key>, when invoking the build referenced by <target-ref>. See also BUILD for more details about the --build-arg option.

CMD (same as Dockerfile CMD)

Synopsis

  • CMD ["executable", "arg1", "arg2"] (exec form)

  • CMD ["arg1, "arg2"] (as default arguments to the entrypoint)

  • CMD command arg1 arg2 (shell form)

Description

The command CMD sets default arguments for an image, when executing as a container. It works the same way as the Dockerfile CMD command.

LABEL (same as Dockerfile LABEL)

Synopsis

  • LABEL <key>=<value> <key>=<value> ...

Description

The LABEL command adds label metadata to an image. It works the same way as the Dockerfile LABEL command.

EXPOSE (same as Dockerfile EXPOSE)

Synopsis

  • EXPOSE <port> <port> ...

  • EXPOSE <port>/<protocol> <port>/<protocol> ...

Description

The EXPOSE command marks a series of ports as listening ports within the image. It works the same way as the Dockerfile EXPOSE command.

ENV (same as Dockerfile ENV)

Synopsis

  • ENV <key> <value>

  • ENV <key>=<value>

Description

The ENV command sets the environment variable <key> to the value <value>. It works the same way as the Dockerfile ENV command.

Note

Do not use the ENV command for secrets used during the build. All ENV values used during the build are persisted within the image itself. See the RUN --secret option to pass secrets to build instructions.

ENTRYPOINT (same as Dockerfile ENTRYPOINT)

Synopsis

  • ENTRYPOINT ["executable", "arg1", "arg2"] (exec form)

  • ENTRYPOINT command arg1 arg2 (shell form)

Description

The ENTRYPOINT command sets the default command or executable to be run when the image is executed as a container. It works the same way as the Dockerfile ENTRYPOINT command.

VOLUME (same as Dockerfile VOLUME)

Synopsis

  • VOLUME <path-to-target-mount> <path-to-target-mount> ...

  • VOLUME ["<path-to-target-mount>", <path-to-target-mount> ...]

Description

The VOLUME command creates a mount point at the specified path and marks it as holding externally mounted volumes. It works the same way as the Dockerfile VOLUME command.

USER (same as Dockerfile USER)

Synopsis

  • USER <user>[:<group>]

  • USER <UID>[:<GID>]

Description

The USER command sets the user name (or UID) and optionally the user group (or GID) to use when running the image and also for any subsequent instructions in the build recipe. It works the same way as the Dockerfile USER command.

WORKDIR (same as Dockerfile WORKDIR)

Synopsis

  • WORKDIR <path-to-dir>

Description

The WORKDIR command strs the working directory for other commands that follow in the recipe. The working directory is also persisted as the default directory for the image. If the directory does not exist, it is automatically created. This command works the same way as the Dockerfile WORKDIR command.

HEALTHCHECK (same as Dockerfile HEALTHCHECK)

Synopsis

  • HEALTHCHECK NONE (disable healthchecking)

  • HEALTHCHECK [--interval=DURATION] [--timeout=DURATION] [--start-period=DURATION] [--retries=N] CMD command arg1 arg2 (check container health by running command inside the container)

Description

The HEALTHCHECK command tells Docker how to test a container to check that it is still working. It works the same way as the Dockerfile HEALTHCHECK command, with the only exception that the exec form of this command is not yet supported.

Options

--interval=DURATION

Sets the time interval between health checks. Defaults to 30s.

--timeout=DURATION

Sets the timeout for a single run before it is considered as failed. Defaults to 30s.

--start-period=DURATION

Sets an initialization time period in which failures are not counted towards the maximum number of retries. Defaults to 0s.

--retries=N

Sets the number of retries before a container is considered unhealthy. Defaults to 3.

SHELL (not supported)

The classical SHELL Dockerfile command is not yet supported. Use the exec form of RUN, ENTRYPOINT and CMD instead and prepend a different shell.

ADD (not supported)

The classical ADD Dockerfile command is not yet supported. Use COPY instead.

ONBUILD (not supported)

The classical ONBUILD Dockerfile command is not supported.

STOPSIGNAL (not supported)

The classical STOPSIGNAL Dockerfile command is not yet supported.