Podman
Podman is an alternative to docker; it's a daemonless container engine for developing, managing and running OCI containers on a Linux system. Podman also works on Mac using a podman machine.
Prerequisites
Mac: ensure a podman machine is running.
Linux: for multi-platform builds, install qemu-user-static.
WITH DOCKER requires rootful mode.
Linux: run with
sudo(i.e.,sudo earthly -P +with-docker-target)Mac: run a rootful machine.
Getting started
When earthly starts a check is done to determine what frontend is available. By default, earthly will attempt to use docker and then fall back to podman. If you wish to change the behavior of the startup check, run the following command:
# Configure earthly to use podman
earthly config global.container_frontend podman-shell
# Configure earthly to use docker
earthly config global.container_frontend docker-shellYou can verify the command worked by checking the ~/.earthly/config.yml file and verifying it contains a container_frontend entry.
Then, you can run a basic hello world example to see earthly using the appropriate container frontend.
If instead you see No frontend initialized, and you're using Mac, it may mean your podman machine is not running.
Known limitations / troubleshooting
Builds running slowly
There are a few steps you should take to rule out common performance bottlenecks.
Mac: check podman resources
At the time of writing this, podman machines use a single core and 2GB of RAM by default. Depending on what you're doing you may need more resources.
Resources can be adjusted by using one of these commands:
Mac: check machine architecture
Running podman version will display the specifications of your podman client and server (machine). You should ensure the architecture in OS/Arch is the same between client and server. This will rule out emulation as a performance bottleneck.
The output may look like this:
In this example, the client us running on an M1 Mac and both the client and server are using arm64.
Check graph driver
Running podman info --debug will show your current podman configuration. VFS and other drivers can perform poorly when compared to overlay and are not recommended by the podman community. Ensure overlay is used by looking for the following in the podman info output:
Mac: docker-credential-desktop: executable file not found in $PATH
This error typically occurs when switching from docker desktop to podman without docker installed. There may be a lingering configuration file that will be read by the attachable used to authenticate calls to buildkit.
To fix this issue, try removing or renaming the ~/.docker/config.json file.
Earthly CLI - no frontend initialized
Seeing the error on startup means the check for podman has failed.
Ensure you have correctly installed podman and, if you are using a Mac, the podman machine is running.
Rootless podman
Running podman in rootless mode is not supported due to the earthly/dind and earthly/buildkit because they require privileged access. Specifically, WITH DOCKER will fail. You must use sudo on Linux or set your podman machine to rootful mode on Mac to use WITH DOCKER.
Podman within WITH DOCKER
WITH DOCKER starts a container with a docker installation. You can only use the podman CLI in the RUN statement if you specify LOCALLY to run it on the host machine; otherwise, you will need to use the docker CLI.
Cross-image targets
You need to configure QEMU if you are running a cross-platform target. If you haven't properly configured QEMU you will receive an error message containing the following message:
We've found installing qemu-user-static will allow cross-platform targets tun run on Linux.
crun: open executable: Permission denied: OCI permission denied
This can happen if you attempt to run (or the ENTRYPOINT references) a binary without the execution permission. https://github.com/containers/podman/issues/9377 https://github.com/signalwire/freeswitch/pull/1748
Last updated
Was this helpful?