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.
- Linux: run with
sudo
(i.e.,sudo earthly -P +with-docker-target
)
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-shell
You can verify the command worked by checking the
~/.earthly/config.yml
file and verifying it contains a container_frontend
entry.> cat ~/.earthly/config.yml
global:
container_frontend: podman-shell
Then, you can run a basic hello world example to see earthly using the appropriate container frontend.
> earthly github.com/earthly/hello-world:main+hello
1. Init 🚀
————————————————————————————————————————————————————————————————————————————————
buildkitd | Starting buildkit daemon as a podman container (earthly-buildkitd)...
buildkitd | ...Done
If instead you see
No frontend initialized
, and you're using Mac, it may mean your podman machine is not running.There are a few steps you should take to rule out common performance bottlenecks.
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:
# Initialize a new default machine with 5 CPUs, 128GB disk space, 8196 MB of memory, and start it
podman machine init --now --cpus 5 --disk-size 128 --memory 8196
# Adjust the current default podman machine to use 5 CPUs, 128GB disk space, and 8196 MB of memory
podman machine stop ; podman machine set --cpus 5 --disk-size 128 --memory 8196 && podman machine start
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:
> podman version
Client: Podman Engine
Version: 4.2.1
API Version: 4.2.1
Go Version: go1.18.6
Built: Tue Sep 6 13:16:02 2022
OS/Arch: darwin/arm64
Server: Podman Engine
Version: 4.2.0
API Version: 4.2.0
Go Version: go1.18.4
Built: Thu Aug 11 08:43:11 2022
OS/Arch: linux/arm64
In this example, the client us running on an M1 Mac and both the client and server are using arm64.
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:> podman info --debug
...
graphDriverName: overlay # or something similar
...
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.Seeing the error on startup means the check for podman has failed.
> earthly github.com/earthly/hello-world:main+hello
1. Init 🚀
————————————————————————————————————————————————————————————————————————————————
frontend | No frontend initialized.
Ensure you have correctly installed podman and, if you are using a Mac, the podman machine is running.
> podman machine start
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.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.
docker-locally:
LOCALLY
WITH DOCKER
RUN podman ps
END
docker:
WITH DOCKER
RUN docker ps
END
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:
> earthly +cross-platform
...
exec /bin/sh: exec format error
...
> apt-get install qemu-user-static
# or
> yum install qemu-user-static
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/1748Last modified 7mo ago