在容器中运行 Antora
Antora 项目提供了一个 Docker 映像，您可以使用它在容器中运行 Antora 命令(这个过程称为 containerization )。这种方法的好处是您可以绕过安装 Antora ，直接开始运行它。你只需要 Docker 或 Podman 。
假设：
-
您的机器上安装了 Docker (command: Docker)或 Podman (command: Podman)。
-
在您的机器上运行 Docker 守护进程(使用 Podman 时不需要)。
-
您已经配置了自己的剧本，或者正在使用 Demo 剧本。
在这一页，你会学到：
-
如何使用官方 Docker 镜像在容器中运行 Antora 。
-
如何让容器访问本地目录。
-
如何扩展 Docker 镜像以创建您自己的镜像。
Antora Docker镜像
Docker 是一个运行容器镜像(正式名称为 OCI 镜像)的工具。您可以将容器映像视为盒子中的应用程序。该框中包含运行应用程序所需的所有内容，包括代码、运行时、设置，甚至操作系统本身。容器不仅将软件与主机环境隔离开来，还使软件易于启动并快速运行。这是发现和探索 Antora 的完美方式！
Antora 项目提供了一个名为 antora/antora 的官方 Docker（OCI）映像，用于在容器内运行 Antora 。该映像已发布到 Docker Hub 上的 antora/antora 项目中。
该映像可以直接替换 antora 命令。您不需要在自己的计算机或 CI 环境中安装 antora 命令，只需运行容器即可运行该命令。实际上，Antora 文档站点的 CI 作业使用此映像生成您当前正在阅读的文档。
让我们看看如何运行它。
运行 Antora 镜像
为了演示如何使用这个图像，我们将使用 Antora 演示站点。首先克隆演示站点的剧本存储库，然后切换到新创建的文件夹：
~ $ git clone https://gitlab.com/antora/demo/docs-site.git && cd "$(basename $_ .git)"接下来，执行 docker run 命令，使用 docker 客户端为该映像调用 entrypoint 命令(即 antora )
docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml该命令从镜像中创建一个新容器，将当前目录挂载在容器内的路径 /Antora 中，运行 Antora 命令（作为当前用户），然后停止并卸下容器。就像运行本地安装的 Antora 命令一样！
与本地路径对齐
如果您使用卷映射 $PWD:/antora:Z ，您可能会注意到 Antora 报告的本地路径不会映射回您的系统。这是因为在 Antora 看来，/antora 是当前的工作目录。为了解决这个问题，您需要将当前的工作目录映射到容器中，然后在运行`Antora` 之前切换到该目录。为此，请改用以下卷挂载：
-v $PWD:$PWD:Z -w $PWD请注意 -w 选项的添加。此选项告诉 Antora 从 /antora 切换到您映射的目录。现在，当 Antora 报告本地路径时，它们将与主机系统上的路径匹配。
选项标志
下面是对 run 命令中使用的一些选项标志的解释：
- -t
-
这个标志分配一个伪
tty，如果您想看到git操作的进度条，这是必需的。如果你不需要看到这些进度条，你可以忽略这个标志。 - -u $(id -u)
-
这个选项告诉 Docker 以当前用户的身份运行 entrypoint 命令(例如，antora)。如果在卷挂载上使用
:Z修饰符而没有指定此选项，则生成的文件(很可能)是以 root 用户的身份写入的(因此删除起来相当棘手)。使用Podman时不需要此选项。 - -v
-
一个卷挂载，将您本地系统的当前目录（表示为
$PWD）映射到容器内部的/antora目录。这允许容器写入的文件在本地系统上可见，这正是使用容器的整个目的。 - :Z (on the volume mount)
-
只有在运行启用了 SELinux 的 Linux 发行版(比如 Fedora )时才需要这个标志。这个选项允许您在运行 SELinux 时使用卷挂载。
- -w
-
此选项告诉 Docker 在调用 entrypoint 命令之前切换到指定的目录（即
$PWD）。如果您想从容器内部的/antora目录以外的目录运行antora命令，则需要使用此选项。 - CAUTION
-
尽管很诱人，但不需要使用
--privileged标志。有关如何在 SELinux 中使用卷挂载的更多信息，请参阅 使用卷与Docker可能会导致SELinux出现问题 的博客文章。
缓存目录位置
如果 Antora 不能写入默认的缓存目录，或者您只是希望缓存目录位于挂载的目录中，请使用 --cache-dir 选项指定剧本相对目录：
docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --cache-dir=./.cache/antora antora-playbook.yml另一种方法是覆盖容器用户的 HOME 目录：
docs-site $ docker run -u $(id -u) -e HOME=/antora -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml在这两种情况下，由 Antora 缓存或生成的所有文件都整齐地包含在挂载的目录中，并归当前用户所有。此配置还有一个好处，即缓存将在两次运行之间保留，因此不加考虑地使用它是一个好主意。
进入容器
如果您希望 shell 进入容器，而不是让它运行 antora 命令，请将 shell 的名称( ash )附加到容器运行命令后：
docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -it antora/antora ash现在，您可以从正在运行的容器中的任何位置运行 antora 命令。此模式在编辑时非常有用。由于容器仍在运行，因此可以快速执行 antora 命令。
如果基础 Antora 图像不包含站点所需的所有内容，则可以扩展它。
扩展 Antora 镜像
您可以使用这个镜像作为您自己的 Docker 镜像的基础。这个图像是预先配置了 Yarn 的，所以你可以安装额外的扩展库，比如 Asciidoctor Kroki ( asciidoctor-kroki )，用于向 AsciiDoc 添加图表支持。
-
克隆 docker-antora 存储库并切换到它
~ $ git clone https://gitlab.com/antora/docker-antora.git && cd "$(basename $_ .git)" -
创建一个名为
Dockerfile.custom的自定义Dockerfile文件。 -
用以下内容填充文件：
Example 1. Example 1. Dockerfile.customFROM antora/antora RUN yarn global add asciidoctor-kroki (1)1 向基础镜像添加自定义扩展。 -
使用以下命令构建镜像
docker-antora $ docker build -t local/antora:custom -f Dockerfile.custom .
构建完成后，您将在计算机上拥有一个名为 local/antora:custom 的新镜像。要查看所有镜像的列表，请运行以下命令：
docker images要运行此镜像，请切换回 playbook 项目并运行容器，如下所示：
docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t local/antora:custom antora-playbook.yml如果您想与其他人共享此镜像，则需要发布它。请参考 Docker文档 了解如何操作。