Using Podman with Quarkus
Podman is a daemonless and rootless container engine for developing, managing, and running OCI Containers on your Linux system or other OS. If you’re using Podman with Quarkus, some one-off setup is needed, but once it’s done, you can take advantage of all the Quarkus features.
Containers are really Linux. As such, Linux containers cannot run natively on macOS or Windows. Therefore, the containers must run in a Linux virtual machine (VM), and a Podman client interacts with that VM. A native hypervisor subsystem and virtualization software is used to run the Linux VM on the OS, and then containers are run within this VM. In Podman, this is known as the Podman machine, and it is built into the tool.
macOS users can install Podman through Homebrew.
Once you have set up
brew, you can use the
brew install command to install Podman and
brew install podman brew install docker-compose podman machine init -v $HOME:$HOME PODMAN_VERSION=`podman -v | sed 's/[a-zA-Z ]*//'` sudo /opt/homebrew/Cellar/podman/$PODMAN_VERSION/bin/podman-mac-helper install podman machine set --rootful podman machine start alias docker='podman'
If you’re using Podman 4.1 or higher, you don’t need the
-v $HOME:$HOME volume mount.
If you’re using Mac M1, an extra step is required to make AMD64 images work:
podman machine ssh sudo -i rpm-ostree install qemu-user-static systemctl reboot
Once the virtual machine restarts, you should be good to run dev services.
For more details, please see
article about running Podman on Mac
another article, with good guidance on
--rootfuland mounting volumes
article about running AMD64 images with Podman on Mac M1
Please see the Podman for Windows guide for setup and usage instructions.
Before starting the Podman machine, set it to prefer rootful container execution:
podman machine set --rootful
This action only needs to be done once.
The Podman package is available in several Linux distributions.
Podman can in most cases be used as an drop-in-replacement for Docker, either with the
podman-docker package, or using an alias (
To install it for your Linux OS, please refer to the Podman installation guide.
Setting DOCKER_HOST on Linux
Podman supports two modes of operation: rootful, in which case the container runs as root on the host system, and rootless, where the container runs under a standard Unix user account.
On Linux, the REST API Unix socket is, by default, restricted to only allow the root user to access it.
This prevents someone from using a container to achieve a privilege escalation on the system.
While these restrictions can be softened to allow a special group instead of just root, the recommended approach is to use rootless Podman on Linux.
To use rootless Podman, you need to set a
DOCKER_HOST environment variable to point to the user-specific socket.
|In both cases, you need to start the REST API by enabling the Podman socket service through systemd, or at least by making sure Podman is running as a service.|
# Example 1: Enable the podman socket with Docker REST API with systemd (only needs to be done once) systemctl --user enable podman.socket --now
# Example 2: Enable the podman socket with Docker REST API on a system where systemd is not running (WSL etc) podman system service --time=0
Then, you can obtain the path of the socket with the following command:
$ podman info | grep -A2 'remoteSocket' remoteSocket: exists: true path: /path/to/podman.sock
DOCKER_HOST environment variable must be done every time or added to the profile:
export DOCKER_HOST=unix:///path/to/podman.sock (1)
For a detailed explanation, see this blog article.
~/.testcontainers.properties and add the following line
Alternatively, you can disable ryuk:
export TESTCONTAINERS_RYUK_DISABLED=true #not recommended - see above!
This has the disadvantage of disabling container cleanup, so you may find stale containers hanging around. This can be a problem if you’re running automated tests.
Short names of images
Testcontainers and Quarkus Dev Services also expect the container service they make requests against to be non-interactive. In case you have multiple registries configured in your Docker or Podman configuration, and when using short image names, Podman responds with a prompt asking which registry should be used to pull images.
While we recommend you to avoid short names and always use fully specified names including the registry, Testcontainers unfortunately relies on short names internally for the time being.
If you are using Testcontainers, either directly or through Dev Services, you need to disable this prompt by setting the
short-name-mode="disabled" configuration property of Podman in