Move docs workflow into Justfile + container

cgwalters · cgwalters · commit 788162f6cf92 · 2025-09-26T15:23:34.000-04:00
This drains nontrivial logic out GHA and into something
isolated via containers and driven via `Justfile` and
easily replicable locally too.

Signed-off-by: Colin Walters &lt;walters@verbum.org&gt;
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -108,39 +108,15 @@ jobs:
           sudo find /ostree/repo/objects -name '*.file' -type f | while read f; do
             sudo fsverity measure $f >/dev/null
           done
-  # Build documentation using mdBook (only for PRs with 'documentation' label)
-  # TODO move into Justfile
+  # Test that we can build documentation
   docs:
-    if: ${{ contains(github.event.pull_request.labels.*.name, 'documentation') }}
     runs-on: ubuntu-24.04
-    env:
-      MDBOOK_VERSION: 0.4.37
     steps:
       - uses: actions/checkout@v4
-      - name: Install mdBook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-      - name: Install mdbook-mermaid
-        run: |
-          tag=$(curl 'https://api.github.com/repos/badboy/mdbook-mermaid/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/badboy/mdbook-mermaid/releases/download/${tag}/mdbook-mermaid-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook-mermaid
-          curl -sSL $url | tar -xz --directory=./mdbook-mermaid
-          echo `pwd`/mdbook-mermaid >> $GITHUB_PATH
-      - name: Install mdbook-linkcheck
-        run: |
-          tag=$(curl 'https://api.github.com/repos/Michael-F-Bryan/mdbook-linkcheck/releases/latest' | jq -r '.tag_name')
-          archive="mdbook-linkcheck.x86_64-unknown-linux-gnu.zip"
-          url="https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/${tag}/${archive}"
-          mkdir mdbook-linkcheck
-          curl -sSL -O $url && unzip ${archive} -d ./mdbook-linkcheck && chmod +x ./mdbook-linkcheck/mdbook-linkcheck
-          echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH
-      - name: Build with mdBook
-        run: cd docs && mdbook-mermaid install && mdbook build
+      - name: Bootc Ubuntu Setup
+        uses: ./.github/actions/bootc-ubuntu-setup
+      - name: Build mdbook
+        run: just build-mdbook
   # Build containers and disk images for integration testing across OS matrix
   build-integration:
     strategy:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -14,53 +14,22 @@ concurrency:
   group: "pages"
   cancel-in-progress: false
 
-# To build the docs locally you can also do e.g.:
-# cargo install mdbook-mermaid
-# cd docs
-# mdbook-mermaid install
-# mdbook serve
-
 jobs:
   build:
-    runs-on: ubuntu-latest
-    env:
-      MDBOOK_VERSION: 0.4.37
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - name: Install mdBook
-        run: |
-          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook
-          curl -sSL $url | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-      - name: Install mdbook-mermaid
-        run: |
-          tag=$(curl 'https://api.github.com/repos/badboy/mdbook-mermaid/releases/latest' | jq -r '.tag_name')
-          url="https://github.com/badboy/mdbook-mermaid/releases/download/${tag}/mdbook-mermaid-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-          mkdir mdbook-mermaid
-          curl -sSL $url | tar -xz --directory=./mdbook-mermaid
-          echo `pwd`/mdbook-mermaid >> $GITHUB_PATH
-      - name: Install mdbook-linkcheck
-        run: |
-          tag=$(curl 'https://api.github.com/repos/Michael-F-Bryan/mdbook-linkcheck/releases/latest' | jq -r '.tag_name')
-          archive="mdbook-linkcheck.x86_64-unknown-linux-gnu.zip"
-          url="https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/${tag}/${archive}"
-          mkdir mdbook-linkcheck
-          curl -sSL -O $url && unzip ${archive} -d ./mdbook-linkcheck && chmod +x ./mdbook-linkcheck/mdbook-linkcheck
-          echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH
+      - name: Bootc Ubuntu Setup
+        uses: ./.github/actions/bootc-ubuntu-setup
+      - name: Build mdbook
+        run: mkdir target && just build-mdbook-to target/docs
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
-      - name: Install mdbook_header_footer
-        run: |
-          cargo install mdbook_header_footer
-      - name: Build with mdBook
-        run: cd docs && mdbook-mermaid install && mdbook build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./docs/book/html
+          path: ./target/docs
 
   deploy:
     environment:
diff --git a/Justfile b/Justfile
@@ -65,6 +65,24 @@ test-container: build-units build-integration-test-image
     podman run --rm --read-only localhost/bootc-units /usr/bin/bootc-units
     podman run --rm localhost/bootc-integration bootc-integration-tests container
 
+build-mdbook:
+    cd docs && podman build -t localhost/bootc-mdbook -f Dockerfile.mdbook
+
+# Generate the rendered HTML to the target DIR directory
+build-mdbook-to DIR: build-mdbook
+    #!/bin/bash
+    set -xeuo pipefail
+    # Create a temporary container to extract the built docs
+    container_id=$(podman create localhost/bootc-mdbook)
+    podman cp ${container_id}:/src/book {{DIR}}
+    podman rm -f ${container_id}
+
+mdbook-serve: build-mdbook
+    #!/bin/bash
+    set -xeuo pipefail
+    podman run --init --replace -d --name bootc-mdbook --rm --publish 127.0.0.1::8000 localhost/bootc-mdbook
+    echo http://$(podman port bootc-mdbook 8000/tcp)
+
 # Update all generated files (man pages and JSON schemas)
 #
 # This is the unified command that:
diff --git a/docs/Dockerfile.mdbook b/docs/Dockerfile.mdbook
@@ -0,0 +1,33 @@
+FROM registry.access.redhat.com/ubi10/ubi:latest
+# An intermediate layer which caches the RPMS
+RUN <<EORUN
+set -xeuo pipefail
+dnf -y install cargo rust jq unzip
+dnf clean all
+EORUN
+# See main Dockerfile for rust caching
+RUN --mount=type=cache,target=/src/target --mount=type=cache,target=/var/roothome <<EORUN
+set -xeuo pipefail
+
+# Bootstrap cargo-binstall
+export PATH=$HOME/.cargo/bin:$PATH
+curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
+
+deps=(mdbook@0.4.52 
+      mdbook-mermaid@0.16.0 
+      mdbook-linkcheck@0.7.7
+      mdbook_header_footer@0.0.3)
+cargo binstall --no-confirm ${deps[@]}
+mv ~/.cargo/bin/* /usr/bin/
+
+EORUN
+# And now actually build the docs
+WORKDIR /src
+COPY . /src
+RUN <<EORUN
+set -xeuo pipefail
+mdbook-mermaid install .
+mdbook build
+EORUN
+CMD ["mdbook", "serve", "-n", "0.0.0.0", "-p", "8000"]
+EXPOSE 8000
diff --git a/docs/book.toml b/docs/book.toml
@@ -16,6 +16,3 @@ footers = [
 
 [output.html]
 additional-js = ["mermaid.min.js", "mermaid-init.js"]
-
-[output.linkcheck]
-optional = true
