Using Podman with Quarkus

Podman 是一个用于在 Linux、Windows 和 Mac 上开发、管理和运行 OCI 容器的开源、无守护程序和无 root 容器引擎。它可用于支持 Quarkus 上的容器功能和开发服务。

Installing Podman

Podman 的安装方法因所使用的操作系统而异，所需步骤也会随着 Podman 的版本而随着时间推移而改变。对于 Mac 和 Windows，我们强烈建议通过 Podman Desktop 图形应用程序进行安装。它是步骤最少的最简单选项，它增加了诸如自动启动之类的附加功能，并有助于管理未来的更新。还提供了可能使用的一个仅限 CLI 的选项。但是，此设置需要附加的手动任务来管理、更新和启动 Podman Machine 环境。

Mac 上的 Homebrew 包管理器 (brew) should not be used to install Podman，因为它会导致未经验证的组件组合。这是由于 Homebrew 在项目之间共享依赖项，以及对升级请求的审查有限。例如，在 Apple Silicon 上更新 qemu 时有几次中断了，从而阻止 Podman 机器 VM 启动。

在 Linux 上，Podman 集成在操作系统中，并通过系统的打包程序管理器安装。与 Mac 和 Windows 一样，Podman Desktop 也可以安装来补充 Podman CLI。但是，在 Linux 上，Podman Desktop 作为本地 Podman 集成的客户端使用，并且不管理底层 Podman 安装。

有关最新版本的 Podman Desktop，请参阅 [role="bare"][role="bare"]https://podman-desktop.io/downloads/。

此外，如果你使用的是 Linux，请参阅 Podman Linux installation documentation了解在你特定的 Linux 发行版中安装 Podman 的说明。

Docker compatibility mode

在 Mac 或 Windows 上安装 Podman Desktop 时，在出现提示时开启 Docker 兼容模式非常重要。这将确保 podman-mac-helper 在你不知情的情况下自动完成设置（你通常在启动后会收到这方面的提示），它对于支持 /var/run/docker.sock（权限较高的位置）至关重要。它还将安装对 Docker Compose 的支持。

Platform differences

尽管在 Mac、Windows 和 Linux 之间交互容器在很大程度上是相同的，但需要了解一些重要的环境差异。尤其是，由于“容器均为 Linux”，因此执行容器的方式不同。更具体地说，容器包含依赖于 Linux 内核 syscall 接口的 Linux 用户区二进制文件。因此，Linux 容器无法在 macOS 或 Windows 上原生运行；相反，它们需要使用运行 Linux 的虚拟机 (VM) 来承载它们。对于需要它的系统，Podman 包括一个用于管理此 VM 的子系统，称为 Podman Machine。Podman Desktop 对此 VM 执行引导式交互设置，并会自动为你启动该 VM。

Rootful vs Rootless

Podman 支持两种操作模式：root 模式（在这种模式下，容器在 Linux 主机上（或者在 Mac/Windows 的情况下在 VM 中）作为 root 运行），以及 rootless 模式（在这种模式下，容器在标准 Unix 用户帐户下运行）。后者提供更强的安全性，但一些容器无法在更高限制下运行。例如，如果容器创建新设备、回环挂载点并执行其他高度受限的操作，那么它们就必须作为 root 运行。请注意，不要将此与容器中指定的 USER 值混淆，该值指的是容器内的进程如何感知自身。在 rootless 中，具有 USER 为“root”的用户在容器中运行的进程会相互显示为 root，但由于 pid 命名空间，它们实际上是在主机系统上以标准受限用户帐户的身份运行。

Configuring on Win & Mac

在涉及 Podman Machine 管理的 VM（Mac 和 Windows）的系统上，容器客户端和 Podman 命令会远程与运行该 VM 的 rootless 或 rootful 系统服务通信。使用哪种服务取决于 Podman 机器中的 `rootful`设置。为了最大限度地确保兼容性，Podman Desktop 默认将新机器实例的 rootful 功能开启。由于 VM 本身在用户进程下运行，因此这对安全性影响有限。也可以通过 Podman 命令来更改此设置：

podman machine set --rootful=true # or false
podman machine stop
podman machine start

Configuring on Linux

在 Linux 系统上，建议使用用户 systemd 服务以 rootless 配置配置客户端访问权限。

可以使用以下命令启用此功能：

systemctl --user enable podman.socket --now

Setting DOCKER_HOST on Linux

在 Linux 上完成上述 rootless 设置后，你需要通过设置 `DOCKER_HOST`环境变量来指向用户服务 podman 套接字，来配置客户端，例如 Quarkus 和 testcontainers。该路径可以设置使用 podman 命令查询该路径的表达式的值：

export DOCKER_HOST=unix://$(podman info --format '{{.Host.RemoteSocket.Path}}')

Other Linux settings

Short names of images

Testcontainers 和 Quarkus Dev Services 还希望其发出请求的容器服务是非交互式的。如果你在 Docker 或 Podman 配置中配置了多个注册表，并且使用较短的图像名称，那么 Podman 会通过提示询问应使用哪个注册表来拉取图像。

尽管我们建议你避免使用较短的名称，并始终使用包括注册表在内的完整指定名称，但 Testcontainers 在目前不幸依靠内部较短的名称。如果你直接或通过 Dev Services 使用 Testcontainers，则需要通过在 `/etc/containers/registries.conf`中设置 Podman 的 `short-name-mode="disabled"`配置属性来禁用此提示。