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

本文档介绍了如何在本地机器上重新创建和运行 docs.rockylinux.org 网站的本地副本。在以下情况下运行文档网站的本地副本可能很有用

您有兴趣了解和参与 docs.rockylinux.org 网站的 Web 开发方面
您是一位作者，您想在贡献文档之前查看它们在 docs 网站上的渲染/外观

创建内容环境¶

确保满足先决条件。如果没有，请跳到“设置先决条件”部分，然后返回此处。
将本地系统上的当前工作目录更改为要进行写作的文件夹。在本文档的其余部分，我们将此目录称为 $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 Web 开发环境¶

确保您的本地机器上已启动并运行 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 以查看网站的本地副本

http://localhost:8001

或

http://SERVER_IP:8001

设置先决条件¶

通过运行以下命令安装和设置 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 socket 的权限。键入

sudo chmod 666 /var/run/docker.sock

注释¶

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

作者：瓦莱·索因卡

贡献者：甘娜·吉尔诺娃