ci: simplify CI build by sharing user guide OCI image with localdev (#254)

Author: Djaytan

.github/release/release.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env sh
+# TODO: move in sources
 
 set -eu
 

.github/workflows/docs-deploy.yml

@@ -24,6 +24,9 @@ jobs:
       # Firewall rules:
       # -> "*.github.com": Standard interactions with GitHub
       # -> "*.pypi.org" & "files.pythonhosted.org": Downloading Python packages
+      # -> "*.docker.io" & "*.docker.com": Standard interactions with Docker
+      # -> "*.alpinelinux.org": Standard interactions with Alpine Linux package repositories
+      # -> "cdn.fwupd.org": Firmware updates (Alpine)
       - name: Harden runner
         uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
         with:
@@ -34,29 +37,32 @@ jobs:
             api.github.com:443
             pypi.org:443
             files.pythonhosted.org:443
+            *.docker.io:443
+            *.docker.com:443
+            dl-cdn.alpinelinux.org:443
+            cdn.fwupd.org:443
 
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
-          fetch-depth: 0 # Required by MkDocs' revisioning feature
+          fetch-depth: 0 # Required by MkDocs' Git-related features
 
-      - name: Setup Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      - name: Login to Docker Hub
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        if: github.event.pull_request.head.repo.fork == false
         with:
-          python-version: 3.13
-
-      - name: Install MkDocs Material
-        run: pip install --require-hashes --requirement docs/user-guide/requirements/requirements.txt
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Copy License
         run: cp LICENSE.md docs/user-guide/src/license.md
 
       - name: Build Site
         working-directory: docs/user-guide/
         env:
-          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
-        run: mkdocs build --strict
+          GITHUB_TOKEN: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
+        run: ./build.sh
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1

.github/workflows/docs-validate.yml

@@ -24,6 +24,9 @@ jobs:
       # Firewall rules:
       # -> "*.github.com": Standard interactions with GitHub
       # -> "*.pypi.org" & "files.pythonhosted.org": Downloading Python packages
+      # -> "*.docker.io" & "*.docker.com": Standard interactions with Docker
+      # -> "*.alpinelinux.org": Standard interactions with Alpine Linux package repositories
+      # -> "cdn.fwupd.org": Firmware updates (Alpine)
       - name: Harden runner
         uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
         with:
@@ -34,26 +37,29 @@ jobs:
             api.github.com:443
             pypi.org:443
             files.pythonhosted.org:443
+            *.docker.io:443
+            *.docker.com:443
+            dl-cdn.alpinelinux.org:443
+            cdn.fwupd.org:443
 
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
-          fetch-depth: 0 # Required by MkDocs' revisioning feature
+          fetch-depth: 0 # Required by MkDocs' Git-related features
 
-      - name: Setup Python
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+      - name: Login to Docker Hub
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0
+        if: github.event.pull_request.head.repo.fork == false
         with:
-          python-version: 3.13
-
-      - name: Install MkDocs Material
-        run: pip install --require-hashes --requirement docs/user-guide/requirements/requirements.txt
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Copy License
         run: cp LICENSE.md docs/user-guide/src/license.md
 
       - name: Build Site
         working-directory: docs/user-guide/
         env:
-          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
-        run: mkdocs build --strict
+          GITHUB_TOKEN: ${{ github.token }} # Avoid exceeding the GitHub API rate limits
+        run: ./build.sh

README.md

@@ -52,7 +52,8 @@ $ docker run -d -it \
 * 🪶 **Lightweight** – ~125 MB
 * 🧘 **Minimalist** – Includes only essential dependencies to reduce image size and surface area.
 * 🧩 **Customizable** – Streamlined and fine-grained configuration options.
-* 📚 **Well-documented** – Comprehensive and structured documentation covering features, configuration, and usage.
+* 📚 **Well-documented** – Comprehensive and structured documentation covering features, configuration, and
+  usage ([link](https://djaytan.github.io/docker-papermc-server/)).
 * 👤 **UID-agnostic** – Supports running the server with a custom/arbitrary UID (typically required when running container
   in [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift)).
 * 🔐 **Rootless by default** – Runs as a non-root user when no custom UID is specified.

docs/user-guide/.gitignore

@@ -1 +1,2 @@
 .cache/
+site/

docs/user-guide/README.md

@@ -48,15 +48,12 @@ That said, unless you have a specific reason, it’s recommended to use `localde
 
 ## ➕ Adding Dependencies
 
-When introducing new dependencies, make sure to update both the **local development environment** and the **CI build environment**, as they are managed
-separately.
+### 🐍 Python Packages
 
-### 💻 Locally
-
-To update the local environment, open the `Dockerfile` and modify the `RUN pip install ...` line to include any additional packages you need.
+Python dependencies are declared in `requirements/requirements.in`.
+After editing this file to include the new packages, run the `requirements/requirements.sh` script.
+This will regenerate `requirements/requirements.txt`, which is the file actually used by both the localdev and CI environments to install dependencies in a consistent and reproducible way.
 
-### 🤖 In CI
+### 🐧 Alpine Linux Packages
 
-Dependencies for the CI environment are declared in `requirements/requirements.in`.
-After editing this file to include the new packages, run the `requirements/requirements.sh` script.
-This will regenerate `requirements/requirements.txt`, which is the file actually used by the CI to install dependencies in a consistent and reproducible way.
+To add Alpine system packages, modify the `Dockerfile` directly.

docs/user-guide/build.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+set -eu
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" > /dev/null 2>&1 && pwd -P)
+
+cd "${SCRIPT_DIR}"
+
+sh mkdocs.sh build --strict

docs/user-guide/mkdocs.sh

@@ -22,14 +22,19 @@ esac
 
 ROOT_PROJECT_DIR="${SCRIPT_DIR}/../.."
 
-echo 'Building Docker image for MkDocs (can take a while - ~1 minutes)'
+echo 'Building Docker image for MkDocs (can take up to a minute)'
 docker build --progress quiet -t docker-papermc-server/mkdocs "${SCRIPT_DIR}"
 
+# Avoid exceeding the GitHub API rate limits
+GITHUB_TOKEN="${GITHUB_TOKEN:-$(gh auth token)}"
+
 echo
 echo 'Running MkDocs:'
+# Avoid permission issues by running the container with the current user ID and group ID
 docker run --rm -p 8000:8000 --name docker-papermc-server-mkdocs \
+  --user "$(id -u):$(id -g)" \
   --volume="${ROOT_PROJECT_DIR}:/run" \
   --workdir /run/docs/user-guide \
-  -e MKDOCS_GIT_COMMITTERS_APIKEY="$(gh auth token)" \
+  -e MKDOCS_GIT_COMMITTERS_APIKEY="${GITHUB_TOKEN}" \
   docker-papermc-server/mkdocs \
   "$@"