Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Recommend podman desktop #39692

Merged
merged 3 commits into from
Mar 27, 2024
Merged

Recommend podman desktop #39692

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f4cfa3d
recomend podman desktop
maxandersen Mar 26, 2024
270f40e
Update docs/src/main/asciidoc/podman.adoc
maxandersen Mar 26, 2024
5c8f0f4
Rework Podman docs
n1hility Mar 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 32 additions & 95 deletions docs/src/main/asciidoc/podman.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,143 +8,80 @@
: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 an open-source, daemonless, and rootless container engine for developing, managing, and running OCI Containers on Linux, Windows and Mac. It can be used to support the container functionality and Dev Services on Quarkus.

Check warning on line 11 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'open source' rather than 'open-source' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'open source' rather than 'open-source' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 11, "column": 34}}}, "severity": "WARNING"}

Check warning on line 11 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'daemonless'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'daemonless'?", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 11, "column": 47}}}, "severity": "WARNING"}

== Installing Podman

=== macOS
Podman's install approach varies depending on the operating system you are using, and the required steps also change over time depending on the version of Podman. For Mac and Windows we highly recommend installing through the Podman Desktop graphical application. It is the simplest option with the least number of steps, it adds additional functionality like automatic start, and it helps manage future updates. There is also a CLI-only option that may be used. However, this setup requires additional manual tasks to manage, update, and launch the Podman Machine environment.

Check warning on line 15 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 15, "column": 75}}}, "severity": "INFO"}

Check warning on line 15 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'using more direct instructions' rather than 'recommend'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'using more direct instructions' rather than 'recommend'.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 15, "column": 194}}}, "severity": "INFO"}

Check warning on line 15 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'might (for possiblity)' or 'can (for ability)' rather than 'may' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'might (for possiblity)' or 'can (for ability)' rather than 'may' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 15, "column": 451}}}, "severity": "WARNING"}

Check warning on line 15 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsWarnings] Consider using 'start' or 'open' rather than 'launch' unless updating existing content that uses the term.

Raw Output:
{"message": "[Quarkus.TermsWarnings] Consider using 'start' or 'open' rather than 'launch' unless updating existing content that uses the term.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 15, "column": 540}}}, "severity": "WARNING"}

Containers are really Linux.
n1hility marked this conversation as resolved.
Show resolved Hide resolved
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 https://brew.sh/[Homebrew].
Once you have set up `brew`, you can use the `brew install` command to install Podman and `docker-compose`:
[WARNING]
====
The Homebrew package manager on Mac (*brew*) *should not be used to install Podman* as it results in an unverified combination of components. This is due to Homebrew sharing dependencies between projects, along with limited vetting of upgrade requests. As an example, there were several instances where an update to qemu broke on Apple Silicon, preventing Podman machine VMs from booting.

Check warning on line 20 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 20, "column": 85}}}, "severity": "INFO"}

Check warning on line 20 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'qemu'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'qemu'?", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 20, "column": 317}}}, "severity": "WARNING"}
====

[source,bash]
----
n1hility marked this conversation as resolved.
Show resolved Hide resolved
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'
----
On Linux, Podman is integrated as part of the operating system, and installed through the system's packager manager. As with Mac, and Windows, Podman Desktop can also be installed to supplement the Podman CLI. However, on Linux, Podman Desktop acts as a client to the native Podman integration, and does not manage the underlying Podman installation.

Check warning on line 23 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'because' or 'while' rather than 'as'.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 23, "column": 32}}}, "severity": "INFO"}

If you're using Podman 4.1 or higher, you don't need the `-v $HOME:$HOME` volume mount.
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:

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]:
n1hility marked this conversation as resolved.
Show resolved Hide resolved
- https://podman-desktop.io/macos/[MacOS]
- https://podman-desktop.io/windows/[Windows]
maxandersen marked this conversation as resolved.
Show resolved Hide resolved
- https://podman-desktop.io/linux/[Linux]

[source,bash]
----
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.
Additionally, if you are using Linux, see the Podman https://podman.io/docs/installation#installing-on-linux[Linux installation documentation] for instructions installing Podman to your specific Linux distribution.

Check warning on line 32 in docs/src/main/asciidoc/podman.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using 'by using' or 'that uses' rather than 'using'.", "location": {"path": "docs/src/main/asciidoc/podman.adoc", "range": {"start": {"line": 32, "column": 25}}}, "severity": "INFO"}

For more details, please see
=== Docker compatibility mode

- 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]
When installing Podman Desktop on Mac or Windows, tt's important to enable Docker compatibility mode when prompted. This will ensure the podman-mac-helper is setup on your behalf (normally a manual action you are prompted to do after start), necessary for supporting /var/run/docker.sock (privileged location). It will also install support for Docker compose.

=== 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.
== Platform differences

Before starting the Podman machine, set it to prefer rootful container execution:
While interacting with containers is mostly identical between Mac, Windows, and Linux, there are important environmental differences to be aware of. Notably, the way in which containers are executed is different, since "Containers are Linux". More specifically, containers contain Linux userland binaries with a dependency on the Linux kernel syscall interface. As such, Linux containers cannot run natively on macOS or Windows; they instead require the use of a virtual machine (VM), running Linux, to host them. For systems that require it, Podman includes a subsystem called Podman Machine that is used to manage this VM. Podman Desktop performs a guided interactive setup of this VM, and will automatically launch it on your behalf.

[source,bash]
----
podman machine set --rootful
----

This action only needs to be done once.

=== Linux
== Rootful vs Rootless

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].
Podman supports two modes of operation: rootful, in which case the container runs as root on the Linux host (or VM in the case of Mac/Windows), and rootless, where the container runs under a standard Unix user account. The latter offers significantly stronger security, but some containers are not capable of running under the increased restrictions. As an example, if a container creates new devices, loopback mount points, and performs other highly restricted operations, then they must be run as root. Note, that this is not to be confused with the USER value specified in Containerfile/Dockerfile, which refers to how processes inside the container perceive themselves. In rootless, processes running in a container with a USER of "root" will appear to each other as root, but due to pid namespacing, they will actually be running as a standard restricted user account on the host system.

=== Setting DOCKER_HOST on Linux
=== Configuring on Win & Mac

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.
On systems which involve a Podman Machine managed VM (Mac & Windows), container clients and Podman commands communicate remotely to either a rootful or rootless system service running the VM. Which is used is determined by the `rootful` setting of the Podman machine. For maximal compatibility, Podman Desktop defaults to enabling rootful for new machine instances. There is limited security impact to this since the VM itself is running under a user process. This can also be changed via the podman commands:

NOTE: 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.

[source,bash]
----
# Example 1: Enable the podman socket with Docker REST API with systemd (only needs to be done once)
systemctl --user enable podman.socket --now
----

[source,bash]
----
# 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:

[source,bash]
podman machine set --rootful=true # or false
podman machine stop
podman machine start
----
$ podman info | grep -A2 'remoteSocket'

remoteSocket:
exists: true
path: /path/to/podman.sock
----
=== Configuring on Linux

Setting the `DOCKER_HOST` environment variable must be done every time or added to the profile:
On Linux systems, it's recommended to configure client access in a rootless configuration using a user systemd service.

This can be enabled using the following command:
[source,bash]
----
export DOCKER_HOST=unix:///path/to/podman.sock <1>
systemctl --user enable podman.socket --now
----
<1> Replace `/path/to/podman.sock` with the path you obtained previously.

For a detailed explanation, see this https://quarkus.io/blog/quarkus-devservices-testcontainers-podman/[blog article].

== After installation
==== Setting DOCKER_HOST on Linux

=== Testcontainers privileges
With the above rootless setup on Linux, you will need to configure clients, such as Quarkus and testcontainers by setting the `DOCKER_HOST` environment variable to point to the user service podman socket. The path be set using an expression which queries the path using the podman command:

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!
export DOCKER_HOST=$(podman info --format '{{.Host.RemoteSocket.Path}}')
----

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.
== Other Linux settings

== 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.

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 `/etc/containers/registries.conf`.

Loading