在本地运行 docs.rockylinux.org 网站进行 Web 开发 | Podman¶

本文档将引导您在本地计算机上重新创建和运行 docs.rockylinux.org 网站的完整本地副本。在以下场景中，运行文档网站的本地副本可能很有用：

您有兴趣了解 docs.rockylinux.org 网站的 Web 开发方面并为其做出贡献
您是一名作者，并且希望在提交文档之前查看您的文档在 docs 网站上的渲染/外观

设置先决条件¶

通过运行以下命令安装和设置 Podman 及其他工具

sudo dnf -y install podman podman-docker git

sudo systemctl enable --now  podman.socket

安装 docker-compose 并使其可执行。输入：

curl -SL https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose

chmod 755 /usr/local/bin/docker-compose

修复 docker 套接字权限。输入：

sudo chmod 666 /var/run/docker.sock

创建内容环境¶

确保满足先决条件。
在您的本地系统上，将当前工作目录更改为您打算进行编写的文件夹。在本指南的其余部分，我们将此目录称为 $ROCKYDOCS。在此处的演示中，在我们的演示系统上，$ROCKYDOCS 指向 $HOME/projects/rockydocs。

如果 $ROCKYDOCS 不存在，请创建它，然后将您的工作目录更改为 $ROCKYDOCS。输入：
```
mkdir -p $HOME/projects/rockydocs
export ROCKYDOCS=${HOME}/projects/rockydocs
cd  $ROCKYDOCS
```
确保您已安装 git (dnf -y install git)。在 $ROCKYDOCS 中，使用 git 克隆官方 Rocky 文档内容仓库。输入：
```
git clone https://github.com/rocky-linux/documentation.git
```
现在您将拥有一个 $ROCKYDOCS/documentation 文件夹。此文件夹是一个 git 仓库，受 git 控制。
同样，使用 git 克隆官方 docs.rockylinux.org 仓库。输入：
```
git clone https://github.com/rocky-linux/docs.rockylinux.org.git
```

现在您将拥有一个 $ROCKYDOCS/docs.rockylinux.org 文件夹。您可以在此文件夹中试验您的 Web 开发贡献。

创建并启动 RockyDocs 网站开发环境¶

确保您的本地计算机上已启动并运行 Podman（您可以使用 systemctl 进行检查）。通过运行以下命令进行测试：
```
systemctl  enable --now podman.socket
```

创建一个新的 docker-compose.yml 文件，内容如下：

version: '2'
services:
  mkdocs:
    privileged: true
    image: rockylinux:9.1
    ports:
      - 8001:8001
    environment:
      PIP_NO_CACHE_DIR: "off"
      PIP_DISABLE_PIP_VERSION_CHECK: "on"
    volumes:
      - type: bind
        source: ./documentation
        target: /app/docs
      - type: bind
        source: ./docs.rockylinux.org
        target: /app/docs.rockylinux.org
    working_dir: /app
    command: bash -c "dnf install -y python3 pip git && \
      ln -sfn  /app/docs   docs.rockylinux.org/docs && \
      cd docs.rockylinux.org && \
      git config  --global user.name webmaster && \
      git config  --global user.email webmaster@rockylinux.org && \
      curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/mike-plugin-changes.patch -o mike-plugin-changes.patch && \
      git apply --reverse --check mike-plugin-changes.patch && \
      /usr/bin/pip3 install --no-cache-dir -r requirements.txt && \
      /usr/local/bin/mike deploy -F mkdocs.yml 9.1 91alias && \
      /usr/local/bin/mike set-default 9.1 && \
      echo  All done && \
      /usr/local/bin/mike serve  -F mkdocs.yml -a  0.0.0.0:8001"

将文件保存为 docker-compose.yml，放在您的 $ROCKYDOCS 工作目录中。

您还可以通过运行以下命令快速下载 docker-compose.yml 文件的副本：

curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/docker-compose-rockydocs.yml -o docker-compose.yml

最后，使用 docker-compose 启动服务。输入：
```
docker-compose  up
```

查看本地 docs.rockylinux.org 网站¶

如果您的 Rocky Linux 系统上正在运行防火墙，请确保端口 8001 已打开。输入：

firewall-cmd  --add-port=8001/tcp  --permanent
firewall-cmd  --reload

在容器启动并运行时，您现在应该可以通过将 Web 浏览器指向以下 URL 来查看您网站的本地副本：

https://:8001

或

http://SERVER_IP:8001

备注¶

本指南中的说明**不是** Rocky 文档作者或内容贡献者的先决条件。
整个环境在 Podman 容器中运行，因此您需要在本地计算机上正确设置 Podman。
该容器基于官方 Rocky Linux 9.1 docker 镜像构建，可在此处获取：https://hub.docker.com/r/rockylinux/rockylinux
容器将文档内容与 Web 引擎 (mkdocs) 分开。
容器启动一个监听端口 8001 的本地 Web 服务器。

作者：Wale Soyinka

贡献者：Ganna Zhyrnova