From 84868c44b4d54f67481073ac7f7f41542b5d0d2a Mon Sep 17 00:00:00 2001
From: Christian Breunig <christian@breunig.cc>
Date: Sun, 30 Aug 2026 15:00:43 +0200
Subject: Docker: T9264: fix container build and publishing

---
 .dockerignore                    |  7 +++++++
 .github/workflows/docs-build.yml |  3 ++-
 README.md                        | 12 ++++++++----
 docker/Dockerfile                | 23 +++++++++++------------
 4 files changed, 28 insertions(+), 17 deletions(-)
 create mode 100644 .dockerignore

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..688f8a85
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,7 @@
+# The docs image builds from the repository root (so it can COPY
+# requirements.txt), but only needs three files. Excluding everything else
+# keeps the build context small — the docs/ tree alone is ~70 MB.
+*
+!requirements.txt
+!docker/entrypoint.sh
+!docker/im-convert.sh
diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml
index 8855b8d9..0de4e1be 100644
--- a/.github/workflows/docs-build.yml
+++ b/.github/workflows/docs-build.yml
@@ -84,7 +84,8 @@ jobs:
       - name: Build docs image (buildx GHA cache)
         uses: docker/build-push-action@v6
         with:
-          context: docker/
+          context: .
+          file: docker/Dockerfile
           load: true
           tags: docs-build:local
           cache-from: type=gha
diff --git a/README.md b/README.md
index 52c24e07..a6acb13a 100644
--- a/README.md
+++ b/README.md
@@ -45,12 +45,16 @@ contributor guide.
 
 ## Build
 
-The recommended build path is the bundled Docker image — it pins Sphinx and
-the MyST/RTD plugin set to the same versions Read the Docs uses, so local
-builds match production.
+The recommended build path is the bundled Docker image — it installs Sphinx
+and the MyST/RTD plugin set from `requirements.txt`, the same pins Read the
+Docs uses, so local builds match production.
+
+Rebuild the image after pulling changes that touch `requirements.txt` or
+`docker/Dockerfile`; a stale image fails with `Could not import extension ...`
+for any newly added plugin.
 
 ```bash
-docker build -t vyos/vyos-documentation docker
+docker build -t vyos/vyos-documentation -f docker/Dockerfile .
 
 # One-shot HTML build
 docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 8598b808..bf4859f0 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -37,16 +37,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     librsvg2-bin \
     poppler-utils
 
-RUN pip3 install --break-system-packages \
-    Sphinx \
-    sphinx-rtd-theme \
-    sphinx-autobuild \
-    sphinx-notfound-page \
-    lxml \
-    myst-parser \
-    sphinx_design \
-    sphinx_llms_txt \
-    sphinx_sitemap
+# Install the Python toolchain from the repository's requirements.txt so the
+# image matches the versions Read the Docs and the virtualenv path use. Do not
+# duplicate the package list here — an unpinned install silently drifts from
+# requirements.txt (a fresh unpinned build resolved Sphinx 9.0.4 against the
+# pinned 7.2.6), so the container and RTD stop building the same docs. This
+# requires the build context to be the repository root, not docker/.
+COPY requirements.txt /tmp/requirements.txt
+RUN pip3 install --break-system-packages -r /tmp/requirements.txt && \
+    rm /tmp/requirements.txt
 
 # Cleanup
 RUN rm -rf /var/lib/apt/lists/*
@@ -56,7 +55,7 @@ EXPOSE 8000
 # Allow password-less 'sudo' for all users in group 'sudo'
 RUN sed "s/^%sudo.*/%sudo\tALL=(ALL) NOPASSWD:ALL/g" -i /etc/sudoers
 
-COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
 
 # We need to convert the entrypoint with appropriate line endings, else
 # there will be an error:
@@ -69,7 +68,7 @@ RUN dos2unix /usr/local/bin/entrypoint.sh
 # directly, since Debian's imagemagick package is built --without-rsvg and
 # its built-in SVG coder can't handle embedded base64 raster <image>
 # elements. See docker/im-convert.sh for the full rationale.
-COPY im-convert.sh /usr/local/bin/im-convert
+COPY docker/im-convert.sh /usr/local/bin/im-convert
 RUN dos2unix /usr/local/bin/im-convert && chmod +x /usr/local/bin/im-convert
 
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
-- 
cgit v1.2.3