在容器中运行Antora

Antora项目提供了一个Docker镜像，您可以使用该镜像在容器中运行antora命令（这个过程称为容器化）。这种方法的好处是您可以跳过安装Antora直接运行它。您只需要Docker或Podman。

假设：

在本页中，您将学到：

Antora的Docker镜像

Docker是一个运行容器镜像（官方OCI镜像）的工具。您可以将容器镜像看作是一个盒子中的应用程序。在这个盒子里包含了运行应用程序所需的一切，包括代码、运行时、设置，甚至操作系统本身。容器不仅可以将软件与主机环境隔离开，还可以让您快速启动和运行。这是发现和探索Antora的完美方式！

Antora项目提供了一个官方的Docker（OCI）镜像，名为antora/antora，用于在容器中运行Antora。该镜像发布在Docker Hub上的antora/antora项目。

这个镜像是antora命令的即插即用替代品。与在您自己的计算机或CI环境中安装antora命令不同，您只需通过运行容器来运行命令。事实上，Antora文档站点的CI作业使用这个镜像来生成您当前正在阅读的文档。

让我们看看如何运行它。

为了演示如何使用这个镜像，我们将使用Antora演示站点。首先克隆演示站点的playbook存储库，然后切换到新创建的文件夹：

~ $ git clone https://gitlab.com/antora/demo/docs-site.git && cd "$(basename $_ .git)"

接下来，执行docker run命令来调用入口命令（即antora）以使用Docker客户端运行此镜像：

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml

这个命令从镜像中启动一个新的容器，将当前目录挂载为容器内的路径/antora，以当前用户身份运行antora命令，然后停止并删除容器。这就像运行本地安装的antora命令一样，只是您使用容器的超级功能来完成！

修复访问/.cache时的权限被拒绝错误

如果您的本地uid（即$(id -u)）不是1000，当在容器中运行Antora时可能会遇到以下错误：

error: EACCES: permission denied, mkdir '/.cache'

这是因为默认的缓存目录是相对于用户的主目录解析的，未映射用户的主目录是/。这就是为什么您在消息中看到路径/.cache，这不是一个可写的位置。

解决这个问题的方法是修改缓存目录的位置。

podman run命令来使用 Podman调用此镜像的入口命令：

docs-site $ podman run -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml

podman替换 docker（并删除 -u选项）。

$PWD:/antora:Z，您可能会注意到Antora报告的本地路径与您的系统不匹配。这是因为在Antora看来， /antora是当前工作目录。为了解决这个问题，您需要将当前工作目录映射到容器中，然后在运行Antora之前切换到它。为此，请使用以下卷挂载：

-v $PWD:$PWD:Z -w $PWD

-w选项。此选项告诉Antora从 /antora切换到您映射的目录。现在，当Antora报告本地路径时，它们将与您主机系统上的路径匹配。

-t
-u $(id -u): antora）。如果您在卷挂载上使用 :Z修饰符而没有指定此选项，则生成的文件（很可能）将以root用户身份编写（因此变得相当棘手）。在使用Podman时 不需要此选项。
-v: $PWD表示）映射到容器内的 /antora目录的卷挂载。这允许容器写入的文件在您的本地系统上可见，这正是使用容器的目的。
:Z（在卷挂载上）
-w: $PWD）。如果您想要从容器内的 /antora目录以外的目录运行 antora命令，则需要使用此选项。

尽管很诱人，但不需要--privileged标志。要了解更多关于在SELinux中使用卷挂载的信息，请参阅博客文章使用Docker卷可能会导致SELinux问题。

缓存目录，或者您只是希望将缓存目录位于挂载目录内，请使用 --cache-dir选项指定一个相对于playbook的目录：

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -t antora/antora --cache-dir=./.cache/antora antora-playbook.yml

docs-site $ docker run -u $(id -u) -e HOME=/antora -v $PWD:/antora:Z --rm -t antora/antora antora-playbook.yml

如果您想要进入容器而不是让其运行antora命令，请将shell的名称（ash）附加到容器运行命令的末尾：

docs-site $ docker run -u $(id -u) -v $PWD:/antora:Z --rm -it antora/antora ash

现在您可以在运行的容器内的任何位置运行antora命令。这种模式在编辑时很有用。由于容器继续运行，您可以快速执行antora命令。

如果基本的 Antora 镜像不包含您站点所需的所有内容，您可以进行扩展。

您可以将此镜像用作自己的 Docker 镜像的基础。该镜像预先配置了 Yarn，因此您可以安装其他扩展库，例如Asciidoctor Kroki（asciidoctor-kroki）用于向 AsciiDoc 添加图表支持。

克隆 docker-antora 存储库并切换到该存储库：

~ $ git clone https://gitlab.com/antora/docker-antora.git && cd "$(basename $_ .git)"

使用以下命令构建镜像：

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 文档以了解如何操作。