Master Earthly: A Modern Docker Image Builder for Faster CI/CD

Earthly Introduction

Start with a single diagram; the functionality relies on hype.

Earthly is a higher‑level Docker image build tool that uses its own Earthfile instead of a traditional Dockerfile. As the official description states:

Makefile + Dockerfile = Earthfile

When building images with Earthly, it heavily relies on BuildKit, extending Dockerfile syntax and integrating Makefile concepts, making multi‑platform builds and code‑centric Dockerfiles simpler. Earthly also improves Dockerfile reuse and CI automation.

Quick Start

2.1 Install Dependencies

Earthly requires Docker and Git. Ensure both are installed before proceeding.

2.2 Install Earthly

Earthly is a single binary written in Go. On Linux you can install it with the official script:

sudo /bin/sh -c 'wget https://github.com/earthly/earthly/releases/latest/download/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly && /usr/local/bin/earthly bootstrap --with-autocomplete'

After installation Earthly starts a buildkitd container named earthly-buildkitd.

2.3 Syntax Highlighting

Earthly provides syntax highlighting for VS Code, VIM, and Sublime Text. See the official documentation for installation details.

2.4 Basic Usage

The following example builds a simple Go program using an Earthfile:

Directory structure:

# Directory structure
~/t/earthlytest ❯❯❯ tree
.
├── Earthfile
└── main.go

0 directories, 2 files

main.go

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

Earthfile

FROM golang:1.17-alpine
WORKDIR /go-example

build:
    COPY main.go .
    RUN go build -o build/go-example main.go
    SAVE ARTIFACT build/go-example /go-example AS LOCAL build/go-example

docker:
    COPY +build/go-example .
    ENTRYPOINT ["/go-example/go-example"]
    SAVE IMAGE go-example:latest

Build the image with:

# Build with Earthly
~/t/earthlytest ❯❯❯ earthly +docker

Run the resulting image from Docker's image list.

Advanced Usage

3.1 Multi‑Stage Builds

Earthfile targets act like Makefile targets and can depend on each other. Each target can run independent commands and use different base images, allowing you to keep only the runtime binary in a minimal image.

3.2 Extended Commands

SAVE

The SAVE command has two forms: SAVE ARTIFACT and SAVE IMAGE.

SAVE ARTIFACT [--keep-ts] [--keep-own] [--if-exists] [--force] <src> [<artifact-dest-path>] [AS LOCAL <local-path>]

SAVE ARTIFACT

copies files from the build environment to an artifact store, optionally also to the host with AS LOCAL.

SAVE IMAGE [--cache-from=<cache-image>] [--push] <image-name>...

GIT CLONE

GIT CLONE

clones a repository into the build environment using the host's Git, avoiding the need for Git inside the container and keeping credentials out of the image.

COPY

The COPY command works like Dockerfile's COPY but can also copy artifacts from other targets, automatically adding dependencies.

# Same as Dockerfile COPY
COPY [options...] <src>... <dest>

# Copy from another target's artifact
COPY [options...] <src-artifact>... <dest>

RUN

RUN

behaves like Dockerfile's RUN with additional flags such as --privileged, --secret, and --ssh. Interactive mode is supported via --interactive options.

# Shell form
RUN [--push] [--entrypoint] [--privileged] [--secret <env-var>=<secret-ref>] [--ssh] [--mount <spec>] -- <command>

# Exec form
RUN [<flags>...], "<executable>", "<arg1>", "<arg2>", ...

3.3 User‑Defined Commands (UDCs)

UDCs allow you to define reusable commands in an Earthfile. Example:

# Define a command
MY_COPY:
    COMMAND
    ARG src
    ARG dest=./
    ARG recursive=false
    RUN cp $(if $recursive = "true"; then printf -r; fi) "$src" "$dest"

# Use in a target
build:
    FROM alpine:3.13
    WORKDIR /udc-example
    RUN echo "hello" >./foo
    DO +MY_COPY --src=./foo --dest=./bar
    RUN cat ./bar # prints "hello"

3.4 Multi‑Platform Builds

Earthly simplifies cross‑compilation by declaring target platforms directly in the Earthfile, eliminating the need to manually configure BuildKit.

Running earthly --push +all builds and pushes images for all declared platforms with a single tag.

Conclusion

Earthly addresses many limitations of Dockerfile, offering a more flexible and reusable workflow with features like multi‑stage builds, extended commands, UDCs, and built‑in multi‑platform support. While there is a learning curve, developers familiar with Dockerfiles can adopt Earthly relatively easily. For deeper details, consult the official documentation.

References

[1] Official documentation: https://earthly.dev/get-earthly

[2] Git authentication guide: https://docs.earthly.dev/docs/guides/auth

[3] Earthfile reference: https://docs.earthly.dev/docs/earthfile

[4] autobuild project: https://github.com/mritd/autobuild

[5] UDCs repository: https://github.com/mritd/autobuild/tree/main/earthfiles/udcs

[6] General guide: https://docs.earthly.dev/docs/guides