Podman Tips

This document contains basic tips for running Podman on Debian and macOS.

Debian 12 (Bookworm)

$ sudo apt-get install podman podman-compose qemu-system-x86
$ podman machine init
$ podman machine start
$ podman machine list

To use Podman rootless, setup fuse-overlayfs:

  1. Install fuse-overlayfs

    $ sudo apt-get install fuse-overlayfs

  2. Configure the current user to use rootless:

    $ cat <<EOF >> ~/.config/containers/storage.conf
[storage]
  driver = "overlay"


[storage.options.overlay]


  mount_program = "/usr/bin/fuse-overlayfs"
EOF

  3. Completely reset the Podman storage to its default state:

    $ podman system reset

  4. Confirm the overlay is being used:

    $ podman info | grep graphDriverName

    This must be overlay. If it's vfs then the fuse filesystem is not being used in rootless mode and building images will be very slow.

See also: - rootless_tutorial - Podman run/build is painfully slow compared to docker

macOS

Install using MacPorts

$ sudo port install podman podman-compose
$ podman machine init
$ podman machine start
$ podman machine list

Configuration

  1. Configure to use with a Docker repository:

    $ cat <<EOF >> ~/.config/containers/registries.conf
unqualified-search-registries = ["docker.io"]
EOF

Short Names

https://www.redhat.com/sysadmin/container-image-short-names

Using Multiple Machines

Create the machine:

$ podman machine init machine-02

Set connection to use:

$ export CONTAINER_CONNECTION=machine-02

or change default connection:

$ podman system list
$ podman system connection default machine-02

Start the machine:

$ podman machine start machine-02

See https://github.com/containers/podman/discussions/13524

Running Older Qemu Host

E.g. to run with a specific version of Fedora 39:

$ podman machine init --image \
https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/39.20240407.3.0/aarch64/fedora-coreos-39.20240407.3.0-applehv.aarch64.raw.gz

Use the Fedora CoreOS Build Browser to find older versions. By default, older versions are hidden. You will probably need to select the option at the bottom of the page to view all.

-- Frank Dean - 06 Jun 2024

Building Multi-Architecture Images on Apple Silicon (arm64)

The following will build a mutli-architecture image using the Dockerfile in the current working directory:

  1. Build an image for each architecture:

    $ podman build --platform linux/amd64 -t myapp:latest-amd64
$ podman build --platform linux/arm64 -t myapp:latest-arm64

  2. Push the images to a repository:

    $ podman push myapp:latest-amd64
$ podman push myapp:latest-arm64

  3. Create a manifest:

    $ podman manifest create myapp:latest myapp:latest-amd64 myapp:latest-arm64
$ podman manifest inspect myapp:latest

  4. Push the manifest:

    $ podman push myapp:latest

  5. Optionally remove the tags for the platform specific builds from the remote registry using the registry's web-interface.

  6. https://developers.redhat.com/articles/2023/11/03/how-build-multi-architecture-container-images#podman

  7. https://blog.while-true-do.io/podman-multi-arch-images/
  8. https://docs.docker.com/build/building/multi-platform/
  9. https://developer.ibm.com/tutorials/running-x86-64-containers-mac-silicon-m1/

-- Frank Dean - 06 Jun 2024

Troubleshooting Issues

Debugging

$ podman --log-level=debug machine start

Fails to Start

Stop any failed QEMU processes, assuming QEMU is not being run for any other purpose :

$ ps -edf | grep -E 'qemu-system.*podman' | grep -v grep | \
  awk '{print $2}' | xargs -I{} kill -9 {}; podman machine stop

See https://podman-desktop.io/docs/troubleshooting/troubleshooting-podman-on-macos

There is an issue when running on Apple Silicon (arm64) where Qemu appears to fail to boot. This can be resolved by installing the afscompress port and decompressing /opt/local/share/qemu/edk2-aarch64-code.fd:

$ afscompress -l /opt/local/share/qemu/edk2-aarch64-code.fd
$ sudo afscompress -d /opt/local/share/qemu/edk2-aarch64-code.fd
$ afscompress -l /opt/local/share/qemu/edk2-aarch64-code.fd

Container using bind mounts fails to start

When the container fails to start with an error similar to the following:

Error: statfs ${SOME_DIRECTORY}: no such file or directory

It is typically caused by a failure to perform a specified bind mount such as:

podman run -v ./:/target -d $SOME_CONTAINER

No space left on device

Re-create the machine with more space:

$ podmand machine rm
$ podman machine init --help
$ podman machine init --disk-size=150

Podman Compose Fails to Find Executable

Error: exec: docker-compose : executable file not found in $PATH

The podman compose command is a thin wrapper to execute an external provider such as docker-compose or podmand-compose. See podman compose --help for more information.

If the command fails to find an executable, define compose_providers in the engine table of containers.conf e.g.:

[engine]
  compose_providers = [ "podman-compose" ]

qemu-x86_64-static: QEMU internal SIGSEGV

Build throws segmentation fault building images on arm64 with fedora 40 and platform set to linux/amd64

qemu-x86_64-static: QEMU internal SIGSEGV {code=MAPERR, addr=0x20}
Segmentation fault (core dumped)

Seems OK on fedora 39:

$ podman machine init --image \
https://builds.coreos.fedoraproject.org/prod/streams/stable/builds/39.20240407.3.0/aarch64/fedora-coreos-39.20240407.3.0-applehv.aarch64.raw.gz

See Issue with run amd64 images on mac arm m1 after recreate podman machine · containers/podman · Discussion #22714

The issue seems to have been fixed in QEMU and should be in releases of QEMU 9.0.0 onwards. The Fedora CoreOS Build Browser can be used to check which version of qemu-user-static-x86 is displayed in the list of packages.

-- Frank Dean - 13 Aug 2024

Error: crun: create keyring ... Disk quota exceeded: OCI runtime error

See https://github.com/containers/podman/issues/23784 and https://github.com/containers/podman/issues/23616

Workaround by restarting the podman machine.

-- Frank Dean - 18 Sep 2024

Resources

-- Frank Dean - 09 Sep 2023

Related Topics: DockerTips, InstallingMacPorts