Skip to content

Commit

Permalink
Rework Podman docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Jason T. Greene <[email protected]>
  • Loading branch information
@n1hility
n1hility committed Mar 27, 2024
1 parent 270f40e commit 5c8f0f4
Showing 1 changed file with 36 additions and 42 deletions.
78 changes: 36 additions & 42 deletions docs/src/main/asciidoc/podman.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,80 +8,75 @@ 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 Linux, Windows and OSX
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"}

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. Although Podman comes with a cli-only installer and is available in various package installers (like brew or Linux package managers) 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.
== Installing Podman

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"}


[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"}
====

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"}

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:

- https://podman-desktop.io/linux/[Linux]
- https://podman-desktop.io/macos/[MacOS]
- https://podman-desktop.io/windows/[Windows]
- https://podman-desktop.io/linux/[Linux]


== Known/Past issues with Podman
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"}

=== Testcontainers privileges
=== Docker compatibility mode

Edit `~/.testcontainers.properties` and add the following line
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.

[source,properties]
----
ryuk.container.privileged=true
----

Alternatively, you can disable ryuk:
== Platform differences

[source,bash]
----
export TESTCONTAINERS_RYUK_DISABLED=true #not recommended - see above!
----
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.

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.
== Rootful vs Rootless

=== Setting DOCKER_HOST on Linux
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.

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.
=== Configuring on Win & Mac

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

[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
podman machine set --rootful=true # or false
podman machine stop
podman machine start
----

Then, you can obtain the path of the socket with the following command:
=== Configuring on Linux

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]
----
$ podman info | grep -A2 'remoteSocket'
remoteSocket:
exists: true
path: /path/to/podman.sock
systemctl --user enable podman.socket --now
----

Setting the `DOCKER_HOST` environment variable must be done every time or added to the profile:
==== Setting DOCKER_HOST on Linux

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:


[source,bash]
----
export DOCKER_HOST=unix:///path/to/podman.sock <1>
export DOCKER_HOST=$(podman info --format '{{.Host.RemoteSocket.Path}}')
----
<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].
== Other Linux settings

=== Short names of images

Expand All @@ -90,4 +85,3 @@ In case you have multiple registries configured in your Docker or Podman configu

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

0 comments on commit 5c8f0f4

Please sign in to comment.