Part 7: Using remote runners
Earthly has the ability to run builds both locally and remotely. If you followed the standard installation instructions, then you most likely have only run local builds so far. In this section, we will explore how to use remote runners to perform builds on remote machines.
Earthly is able to use remote runners for performing builds on remote machines. When Earthly uses a remote runner, the inputs of the build are picked up from the local environment, then the execution takes place remotely, including any pushes (
RUN --push commands, and SAVE IMAGE --push commands), but any local outputs are sent back to the local environment. All this takes place while your local Earthly process still provides the logs of the build in real time locally.Remote runners are especially useful in a few specific circumstances:
- You want to reuse cache between CI runs to dramatically speed up builds (more on this in part 8).
- You want to share compute and cache with coworkers and/or with the CI.
- You have a build that requires a lot of resources, and you want to run it on a machine with more resources than your local machine.
- You have a build that requires running on a specific CPU architecture natively.
- You have a slow internet connection.
There are two types of remote runners:
- Remote Buildkit (self-hosted)
- Earthly Satellites (managed by Earthly)
Earthly Satellites are remote runners managed by the Earthly team. They are a paid feature as part of the Earthly Satellites or Earthly CI plans, but there is a 14-day free trial.
To get started, first you need to create an Earthly Cloud account.
earthly account register --email <your-email>
Follow instructions in the email received to complete the registration. You will additionally need to create an organization.
earthly org create my-org
You must subscribe to a paid plan to use Earthly Satellites. The subscription has a 14-day trial -- your credit card is not charged if you cancel before then.
Then, you can create a satellite.
earthly sat launch my-satellite
Once a satellite has been launched it is automatically selected for use. If you ever need to switch the satellite yourself, you can use the command...
earthly sat select my-satellite
Additionally, you can go back to performing local builds with the command...
earthly sat unselect
And then run Earthly builds as usual.
earthly +my-target
Or, you can use a satellite as part of the build without selecting first
earthly --sat my-satellite +my-target
When running remote builds, some operations might require access to secrets. For example, if you are pushing images to a private registry, or if you are logged in to DockerHub to prevent rate limiting. Earthly will automatically pass the credentials from your local machine to the remote runner.
Any secret that is available locally, including Docker/Podman credentials, will be passed to the remote runner whenever needed by the build.
For more information about secrets, see the Args and secrets page and the authenticating Git and image registries page.