Earthfile reference
Last updated
Was this helpful?
Last updated
Was this helpful?
Earthfiles are comprised of a series of target declarations and recipe definitions. Earthfiles are named Earthfile
, regardless of their location in the codebase.
Earthfiles have the following rough structure:
Each recipe contains a series of commands, which are defined below. For an introduction into Earthfiles, see the .
FROM <image-name>
FROM [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-key>=<build-arg-value>...]
Examples:
Classical reference: FROM alpine:latest
Local reference: FROM +another-target
Relative reference: FROM ./subdirectory+some-target
or FROM ../otherdirectory+some-target
Absolute reference: FROM /absolute/path+some-target
--<build-arg-key>=<build-arg-value>
--platform <platform>
Specifies the platform to build on.
--allow-privileged
Allows remotely-referenced targets to request privileged capabilities; this flag has no effect when referencing local targets.
Additionally, for privileged capabilities, earthly must be invoked on the command line with the --allow-privileged
(or -P
) flag.
For example, consider two Earthfiles, one hosted on a remote GitHub repo:
and a local Earthfile:
then one can build my-target
by invoking earthly with the --allow-privileged
(or -P
) flag:
--build-arg <key>=<value>
(deprecated)
This option is deprecated. Use --<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)
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.
--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 earthly
invocation to enable pushing. For example
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.
--no-cache
Force the command to run every time; ignoring any cache. Any commands following the invocation of 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
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
Might become the following in an Earthfile
--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 earthly
command. Example:
--secret <env-var>=<secret-ref> | <secret-id>
Makes available a secret, in the form of an env var (its name is defined by <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>
.
The <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>
.
Here is an example that showcases both syntaxes:
An empty string is also allowed for <secret-ref>
, allowing for optional secrets, should it need to be disabled.
It is also possible to mount a secret as a file with RUN --mount type=secret,id=+secret/secret-id,target=/path/of/secret,mode=0400
. See --mount
below.
--ssh
Allows a command to access the ssh authentication client running on the host via the socket which is referenced by the environment variable SSH_AUTH_SOCK
.
Here is an example:
--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
type
The type of the mount. Currently only cache
, tmpfs
, and secret
are allowed.
type=cache
target
The target path for the mount.
target=/var/lib/data
mode
The permission of the mounted file, in octal format (the same format the chmod unix command line expects).
mode=0400
id
The secret ID for the contents of the target
file, only applicable for type=secret
.
id=+secrets/password
sharing
The sharing mode (locked
, shared
, private
) for the cache mount, only applicable for type=cache
.
sharing=shared
For cache mounts, the sharing mode can be one of the following:
locked
(default) - the cache mount is locked for the duration of the execution, other concurrent builds will wait for the lock to be released.
shared
- the cache mount is shared between all concurrent builds.
private
- if another concurrent build attempts to use the cache, a new (empty) cache will be created for the concurrent build.
Examples:
Persisting cache for a single RUN
command, even when its dependencies change:
Note that mounts cannot be shared between targets, nor can they be shared within the same target, if the build-args differ between invocations.
Mounting a secret as a file:
The contents of the secret /root/.netrc
file can then be specified from the command line as:
or by passing the contents of an existing file from the host filesystem:
--interactive
/ --interactive-keep
Opens an interactive prompt during the target build. An interactive prompt must:
Be the last issued command in the target, with the exception of SAVE IMAGE
commands. This also means that you cannot FROM
a target containing a RUN --interactive
.
Be the only --interactive
target within the run.
Not be within a LOCALLY
-designated target.
Examples:
Start an interactive python REPL:
Start 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)
The command COPY
allows copying of files and directories between different contexts.
The classical form of the COPY
command differs from Dockerfiles in two cases:
URL sources are not yet supported.
Absolute paths are not supported - sources in the current directory cannot be referenced with a leading /
--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).
If the directories were copied without the use of --dir
, then their contents would be merged into the destination.
--<build-arg-key>=<build-arg-value>
Note that build args and the artifact references they apply to need to be surrounded by parenthesis:
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
--keep-own
Instructs Earthly to keep file ownership information. This applies only to the artifact form and has no effect otherwise.
--if-exists
Only copy source if it exists; if it does not exist, earthly will simply ignore the COPY command and won't treat any missing sources as failures.
--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
... would be equivalent to final-target
in the following Earthfile
--platform <platform>
In artifact form, it specifies the platform to build the artifact on.
--allow-privileged
--build-arg <key>=<value>
(deprecated)
The option --build-arg
is deprecated. Use --<build-arg-key>=<build-arg-value>
instead.
Assuming the following directory tree, of a folder named test
:
Here is how the following copy commands will behave:
One can also copy from other Earthfile targets:
Parentheses are required when passing build-args:
ARG [--required] <name>[=<default-value>]
(constant form)
ARG [--required] <name>=$(<default-value-expr>)
(dynamic form)
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.
In its constant form, the arg takes a default value defined as a constant string. If the <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.
If an 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.
The value of an arg can be overridden either from the earthly
command
or from a command from another target, when implicitly or explicitly invoking the target containing the ARG
for example
--required
A 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 ""
.
SAVE ARTIFACT [--keep-ts] [--keep-own] [--if-exists] [--force] <src> [<artifact-dest-path>] [AS LOCAL <local-path>]
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 <artifact-dest-path>
is not specified, it is inferred as /
.
Important
Note that there is a distinction between a directory artifact and file artifact when it comes to local output. When saving an artifact locally, a directory artifact will replace the destination entirely, while a file (or set of files) artifact will be copied into the destination directory.
Important
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
--keep-own
Instructs Earthly to keep file ownership information.
--if-exists
Only save artifacts if they exists; if not, earthly will simply ignore the SAVE ARTIFACT command and won't treat any missing sources as failures.
--force
Force save operations which may be unsafe, such as writing to (or overwriting) a file or directory on the host filesystem located outside of the context of the directory containing the Earthfile.
Assuming the following directory tree, of a folder named test
:
Here is how the following 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)
In the output form, the command SAVE IMAGE
marks the current build environment as the image of the target and assigns one or more output image names.
Important
--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.
If inline caching is enabled, the --push
option also instructs Earthly to use the specified image names as cache sources.
The actual push is not executed by default. Add the --push
flag to the earthly invocation to enable pushing. For example
--cache-from=<cache-image>
--cache-hint
BUILD [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-name>=<build-arg-value>...]
--<build-arg-key>=<build-arg-value>
Sets a value override of <build-arg-value>
for the build arg identified by <build-arg-key>
.
The override value of a build arg may be a constant string
or an expression involving other build args
or a dynamic expression, based on the output of a command executed in the context of the build environment.
Dynamic expressions are delimited by $(...)
.
--platform <platform>
Specifies the platform to build on.
This flag may be repeated in order to instruct the system to perform the build for multiple platforms. For example
--allow-privileged
--build-arg <build-arg-key>=<build-arg-value>
(deprecated)
This option is deprecated. Please use --<build-arg-key>=<build-arg-value>
instead.
VERSION [options...] <version-number>
The command 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
initial functionality will be preserved
0.6
--use-copy-include-patterns --referenced-save-only --for-in --require-force-for-unsafe-saves --no-implicit-ignore
Individual features may be enabled by setting the corresponding feature flag. New features start off as experimental, which is why they are disabled by default. Once a feature reaches maturity, it will be enabled by default under a new version number.
GIT CLONE [--branch <git-ref>] [--keep-ts] <git-url> <dest-path>
The command GIT CLONE
clones a git repository from <git-url>
, optionally referenced by <git-ref>
, into the build environment, within the <dest-path>
.
--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.
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
FROM DOCKERFILE [options...] <context-path>
The FROM DOCKERFILE
command initializes a new build environment, inheriting from an existing Dockerfile. This allows the use of Dockerfiles in Earthly builds.
-f <dockerfile-path>
--build-arg <key>=<value>
Sets a value override of <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>
In a multi-stage Dockerfile, sets the target to be used for the build. This option is similar to the docker build --target <target-name>
option.
--platform <platform>
Specifies the platform to build on.
The clause 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.
The clause WITH DOCKER
automatically implies the RUN --privileged
flag.
A typical example of a WITH DOCKER
clause might be:
--pull <image-name>
Pulls the Docker image <image-name>
from a remote registry and then loads it into the temporary Docker daemon created by WITH DOCKER
.
This option may be repeated in order to provide multiple images to be pulled.
--load <image-name>=<target-ref>
Builds the image referenced by <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)
.
This option may be repeated in order to provide multiple images to be loaded.
--compose <compose-file>
Loads the compose definition defined in <compose-file>
, adds all applicable images to the pull list and starts up all applicable compose services within.
This option may be repeated, thus having the same effect as repeating the -f
flag in the docker-compose
command.
--service <compose-service>
Specifies which compose service to pull and start up. If no services are specified and --compose
is used, then all services are pulled and started up.
This option can only be used if --compose
has been specified.
This option may be repeated in order to specify multiple services.
--platform <platform>
Specifies the platform for any referenced --load
and --pull
images.
--allow-privileged
--build-arg <key>=<value>
(deprecated)
This option is deprecated. Please use --load <image-name>=(<target-ref> --<build-arg-key>=<build-arg-value>)
instead.
The 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.
A very common pattern is to use the POSIX shell [ ... ]
conditions. For example the following marks port 8080
as exposed if the file ./foo
exists.
Important
Changes to the filesystem in any of the conditions are not preserved. If a file is created as part of a condition, then that file will not be present in the build environment for any subsequent commands.
--privileged
--ssh
--no-cache
--mount <mount-spec>
--secret <env-var>=<secret-ref>
Enable via VERSION 0.6
.
The 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.
The expression may be either a constant list of items (e.g. 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
).
Important
Changes to the filesystem in expressions are not preserved. If a file is created as part of a FOR
expression, then that file will not be present in the build environment for any subsequent commands.
As an example, FOR
may be used to iterate over a list of files for compilation
As another example, FOR
may be used to iterate over a set of directories in a monorepo and invoking targets within them.
--sep <separator-list>
The list of separators to use when tokenizing the output of the expression. If unspecified, the separator list defaults to [tab]
, [new line]
and [space]
(\t\n
).
--privileged
--ssh
--no-cache
--mount <mount-spec>
--secret <env-var>=<secret-ref>
The WAIT
clause executes the encapsulated commands and waits for them to complete. This includes pushing and outputting local artifacts -- a feature which can be used to control the order of interactions with the outside world.
Even though the WAIT
clause limits parallelism by forcing everything within it to finish executing before continuing, the commands within a WAIT
block execute in parallel.
As an example, multiple WAIT
blocks can be used; the first block builds and pushes to a remote registry (in parallel), then a second WAIT
block can be used to execute a script which requires those images to exist in the remote registry:
One can also use a WAIT
block to control the order in which a SAVE ARTIFACT ... AS LOCAL
command is executed:
The CACHE
command creates a cache mountpoint at <mountpoint>
in the build environment. The cache mountpoint is a directory which is shared between the instances of the same build target. The contents of the cache mountpoint are preserved between builds, and can be used to share data across builds.
At the end of the target, the contents of the cache mountpoint are persisted as an additional layer in the image. This means that the contents are available to subsequent targets in the same build using FROM
, or to any saved images SAVE IMAGE
.
--sharing <sharing-mode>
The sharing mode for the cache mount, from one of the following:
locked
(default) - the cache mount is locked for the duration of the execution, other concurrent builds will wait for the lock to be released.
shared
- the cache mount is shared between all concurrent builds.
private
- if another concurrent build attempts to use the cache, a new (empty) cache will be created for the concurrent build.
LOCALLY
The 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.
Only 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.
For example, the following Earthfile will display the current user, hostname, and directory where the Earthfile is stored:
COMMAND
Unlike performing a BUILD +target
, UDCs inherit the build context and the build environment from the caller.
UDCs create their own 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>
.
Global imports and global args are inherited from the 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>...]
Unlike performing a BUILD +target
, UDCs inherit the build context and the build environment from the caller.
UDCs create their own 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>]
If not provided, the <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
.
The <project-ref>
can be a reference to any directory other than .
. If the reference ends in ..
, then mentioning AS <alias>
is mandatory.
If an 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
CMD ["executable", "arg1", "arg2"]
(exec form)
CMD ["arg1, "arg2"]
(as default arguments to the entrypoint)
CMD command arg1 arg2
(shell form)
LABEL <key>=<value> <key>=<value> ...
EXPOSE <port> <port> ...
EXPOSE <port>/<protocol> <port>/<protocol> ...
ENV <key> <value>
ENV <key>=<value>
ENTRYPOINT ["executable", "arg1", "arg2"]
(exec form)
ENTRYPOINT command arg1 arg2
(shell form)
VOLUME <path-to-target-mount> <path-to-target-mount> ...
VOLUME ["<path-to-target-mount>", <path-to-target-mount> ...]
USER <user>[:<group>]
USER <UID>[:<GID>]
WORKDIR <path-to-dir>
HEALTHCHECK NONE
(disable health checking)
HEALTHCHECK [--interval=DURATION] [--timeout=DURATION] [--start-period=DURATION] [--retries=N] CMD command arg1 arg2
(check container health by running command inside the container)
--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
.
HOST <hostname> <ip>
The HOST
command creates a hostname entry (under /etc/hosts
) that causes <hostname>
to resolve to the specified <ip>
address.
The FROM
command initializes a new build environment and sets the base image for subsequent instructions. It works similarly to the classical , but it has the added ability to use another 's image as the base image.
Remote reference from a public or git repository: FROM github.com/example/project+remote-target
The 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 .
Sets a value override of <build-arg-value>
for the build arg identified by <build-arg-key>
. See also for more details about build args.
For more information see the .
The RUN
command executes commands in the build environment of the current target, in a new layer. It works similarly to the , with some added options.
For more information on how to use secrets see the . See also the .
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 . 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 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.
The 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 .
To prevent Earthly from copying unwanted files, you may specify file patterns to be excluded from the build context using an file. This file has the same syntax as a .
Sets a value override of <build-arg-value>
for the build arg identified by <build-arg-key>
, when building the target containing the mentioned artifact. See also for more details about the build arg options.
For more information see the .
Same as .
For detailed examples demonstrating how other scenarios may function, please see our .
This command works similarly to the , 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 .
For more information on how to use build args see the . A number of builtin args are available and are pre-filled by Earthly. For more information see .
This behaviour can be changed with the experimental . This feature additionally allows shelling-out in any earthly command.
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. Note that local artifacts are only produced by targets that are run directly with earthly
, or when invoked using .
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 .
As of , local artifacts are only saved .
For detailed examples demonstrating how other scenarios may function, please see our .
In the cache hint form, it instructs Earthly that the current target should be included as part of the explicit cache. For more information see the .
As of , the --referenced-save-only
feature flag is enabled by default. Images are only saved .
Adds additional cache sources to be used when --use-inline-cache
is enabled. For more information see the .
Instructs Earthly that the current target should be included as part of the explicit cache. For more information see the .
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 . 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).
For more information see the .
Same as .
All features are described in .
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 passed on to earthly
, whereas RUN git clone
would require additional secrets passing, if the repository is not publicly accessible.
The <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 , pointing to a directory containing a Dockerfile
.
Specify an alternative Dockerfile to use. The <dockerfile-path>
can be either a path on the host system, relative to the current Earthfile, or an pointing to a Dockerfile.
It is possible to split the Dockerfile
and the build context across two separate :
For more information see the .
The WITH DOCKER
clause only supports the command . 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 &&
.
For more examples, see the and the .
For information on using WITH DOCKER
with podman see the
The 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 .
For more information see the .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
Same as .
The 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 .
For more information see the .
The command DO
expands and executes the series of commands contained within a user-defined command (UDC) .
For more information see the .
Same as .
The command IMPORT
aliases a project reference (<project-ref>
) that can be used in subsequent .
For more information see the .
Similar to , extend the ability to request privileged capabilities to all invocations of the imported alias.
The command CMD
sets default arguments for an image, when executing as a container. It works the same way as the .
The LABEL
command adds label metadata to an image. It works the same way as the .
The EXPOSE
command marks a series of ports as listening ports within the image. It works the same way as the .
The ENV
command sets the environment variable <key>
to the value <value>
. It works the same way as the .
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 to pass secrets to build instructions.
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 .
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 .
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 .
The WORKDIR
command sets the working directory for following commands 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 .
The HEALTHCHECK
command tells Docker how to test a container to check that it is still working. It works the same way as the , with the only exception that the exec form of this command is not yet supported.
The classical is not yet supported. Use the exec form of RUN
, ENTRYPOINT
and CMD
instead and prepend a different shell.
The classical is not yet supported. Use instead.
The classical is not supported.
The classical is not yet supported.