ci: run the docs pipeline on the agent's local backend (no container images)

.woodpecker.yml

@@ -10,12 +10,22 @@
 # Any change to how the site is built belongs in publishing/, never here.
 #
 # Run model: MANUAL ONLY for now. The Gitea webhook that fires this on push is
-# deliberately NOT wired yet — the Woodpecker instance must first be restricted
-# (done), connected to Gitea via OAuth (pending, see the operator runbook), and
-# proven by a manual run. Once those hold, add `push` to the `when` block below
-# and register the webhook in Gitea.
+# deliberately NOT wired — the poll watcher (docs-deploy-poll.service on the
+# agent host) remains the live auto-deploy path until a manual run has proven
+# the pipeline. Once it has, add `push` to the `when` block below and register
+# the webhook in Gitea.
 #
-# Secrets required (Woodpecker repo/org secret, name `cloudron_token`):
+# Backend note (IMPORTANT — this is why there are no container images here):
+#   The co-op's Woodpecker agent runs as a Cloudron app, which has no Docker
+#   socket, so it uses Woodpecker's `local` backend. Under `local` each step is
+#   run as a shell command INSIDE the agent container, and the step's `image:`
+#   field selects the SHELL, not a container image. Every tool the steps need is
+#   therefore baked into the agent image (co-op/woodpecker-agent):
+#     python3 + the pinned MkDocs toolchain (venv at /opt/docs-venv, mirroring
+#     publishing/requirements.txt), node + the cloudron CLI, bash, git, tar.
+#   If the toolchain pin changes, rebuild that image — see its Dockerfile.
+#
+# Secrets required (Woodpecker repo secret, name `cloudron_token`):
 #   cloudron_token = the Cloudron API token used by publishing/deploy.sh
 # Do not put credentials in this file.
 
@@ -23,30 +33,19 @@ when:
   - event: manual
 
 steps:
-  - name: install
-    image: python:3.12-slim-bookworm
-    commands:
-      # Pinned toolchain — the same file publishing/build.sh installs into its
-      # own .venv-docs. We pre-create that venv so build.sh reuses it verbatim.
-      - python3 -m venv .venv-docs
-      - .venv-docs/bin/pip install --quiet --upgrade pip
-      - .venv-docs/bin/pip install --quiet -r publishing/requirements.txt
-
   - name: build
-    image: python:3.12-slim-bookworm
+    image: bash
     commands:
-      # Reuses .venv-docs created above; build.sh only installs if it is missing.
-      - publishing/build.sh
+      # Reuses the toolchain pre-installed in the agent image; build.sh only
+      # creates/installs a venv if the one given is missing, which it is not.
+      - publishing/build.sh /opt/docs-venv
 
   - name: deploy
-    image: node:20-bookworm-slim
+    image: bash
     commands:
-      # deploy.sh drives the Cloudron `cloudron` CLI (a node script) via
-      # `cloudron exec`; it needs node, the CLI, bash, git and tar.
-      - apt-get update
-      - apt-get install -y --no-install-recommends bash git tar ca-certificates
-      - npm install -g cloudron
-      # Deploy the build produced by the `build` step above (shared workspace).
+      # deploy.sh drives the Cloudron `cloudron` CLI (a node program) via
+      # `cloudron exec`; node, the CLI, bash, git and tar are all in the agent
+      # image. The build it publishes is the shared workspace .site-build/.
       - publishing/deploy.sh
     environment:
       CLOUDRON_TOKEN: