diff --git a/docs/src/main/asciidoc/podman.adoc b/docs/src/main/asciidoc/podman.adoc index fedc6a2767307e..5b668143fb17a0 100644 --- a/docs/src/main/asciidoc/podman.adoc +++ b/docs/src/main/asciidoc/podman.adoc @@ -8,73 +8,37 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc :topics: podman,devops,tooling include::_attributes.adoc[] -https://podman.io/[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. +https://podman.io/[Podman] is a daemonless and rootless container engine for developing, managing, and running OCI Containers on Linux, Windows and OSX -== Installing Podman +Podman's approach varies dependent on the operating system you are using and also varied over time dpeendent on version of Podman. Thus albeit Podman comes with a cli based installer and available in various custom package installers (like brew or Linux package mangers) our default recommendation is to use the official Podman Desktop installer. This will ensure you get the best Developer Joy experience and support for your operating system. -=== macOS +See https://podman-desktop.io/downloads/ for the latest version of Podman Desktop or pick the version that suits your operating system from the list below: -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. +- https://podman-desktop.io/linux/[Linux] +- https://podman-desktop.io/macos/[MacOS] +- https://podman-desktop.io/windows/[Windows] -macOS users can install Podman through https://brew.sh/[Homebrew]. -Once you have set up `brew`, you can use the `brew install` command to install Podman and `docker-compose`: -[source,bash] ----- -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' ----- +== Known/Past issues with Podman -If you're using Podman 4.1 or higher, you don't need the `-v $HOME:$HOME` volume mount. +=== Testcontainers privileges -If you're using Mac M1, an extra step is required to https://edofic.com/posts/2021-09-12-podman-m1-amd64[make AMD64 images work]: +Edit `~/.testcontainers.properties` and add the following line -[source,bash] +[source,properties] ---- -podman machine ssh -sudo -i -rpm-ostree install qemu-user-static -systemctl reboot +ryuk.container.privileged=true ---- -Once the virtual machine restarts, you should be good to run dev services. - -For more details, please see - -- the https://podman.io/getting-started/installation#macos[official Podman documentation] -- article about https://www.redhat.com/sysadmin/replace-docker-podman-macos[running Podman on Mac] -- https://xphyr.net/post/podman_on_osx/[another article], with good guidance on `--rootful` and mounting volumes -- article about https://edofic.com/posts/2021-09-12-podman-m1-amd64[running AMD64 images with Podman on Mac M1] - -=== Windows - -Please see the https://github.com/containers/podman/blob/main/docs/tutorials/podman-for-windows.md[Podman for Windows guide] for setup and usage instructions. - -Before starting the Podman machine, set it to prefer rootful container execution: +Alternatively, you can disable ryuk: [source,bash] ---- -podman machine set --rootful +export TESTCONTAINERS_RYUK_DISABLED=true #not recommended - see above! ---- -This action only needs to be done once. - -=== Linux - -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 (`alias docker=podman`). -To install it for your Linux OS, please refer to the https://podman.io/getting-started/installation#installing-on-linux[Podman installation guide]. +This has the disadvantage of https://github.com/containers/podman/discussions/14238[disabling container cleanup], so you may find stale containers hanging around. +This can be a problem if you're running automated tests. === Setting DOCKER_HOST on Linux @@ -119,28 +83,7 @@ export DOCKER_HOST=unix:///path/to/podman.sock <1> For a detailed explanation, see this https://quarkus.io/blog/quarkus-devservices-testcontainers-podman/[blog article]. -== After installation - -=== Testcontainers privileges - -Edit `~/.testcontainers.properties` and add the following line - -[source,properties] ----- -ryuk.container.privileged=true ----- - -Alternatively, you can disable ryuk: - -[source,bash] ----- -export TESTCONTAINERS_RYUK_DISABLED=true #not recommended - see above! ----- - -This has the disadvantage of https://github.com/containers/podman/discussions/14238[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 +=== 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.