fixing typo on README, improving CI checks

.github/workflows/build-page.yaml

@@ -11,6 +11,9 @@ on:
       - 'trento-docs-site/**'
       - 'trento-docs-site-ui/build/ui-bundle.zip'
       - '.github/workflows/build-page.yaml'
+      - '.tool-versions'
+      - 'versions.yml'
+      - 'scripts/**'
   workflow_dispatch:
   schedule:
     - cron: '0 13 * * 4' # Every Thursday at 1:00 PM UTC
@@ -22,16 +25,30 @@ concurrency:
 permissions:
   contents: read
 jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    outputs:
+      node_image: ${{ steps.read-image.outputs.image }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Read Node.js image from versions.yml
+        id: read-image
+        run: echo "image=$(scripts/check-node-version.sh image)" >> "$GITHUB_OUTPUT"
+
   build:
+    needs: prepare
     runs-on: ubuntu-24.04
-    # openSUSE-based SUSE BCI image with Node.js 24 preinstalled
+    # SUSE BCI image taken from versions.yml, the same one docker-compose.yml uses
     container:
-      image: registry.suse.com/bci/nodejs:24
+      image: ${{ needs.prepare.outputs.node_image }}
     steps:
     - name: Checkout repository
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       with:
         fetch-depth: 0
+    - name: Check the Node.js version against .tool-versions
+      run: scripts/check-node-version.sh
     - name: Configure Pages
       if: github.event_name != 'pull_request'
       uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

.github/workflows/extension-tests.yaml

@@ -11,6 +11,9 @@ on:
       - 'trento-docs-site/package.json'
       - 'trento-docs-site/package-lock.json'
       - '.github/workflows/extension-tests.yaml'
+      - 'versions.yml'
+      - '.tool-versions'
+      - 'scripts/**'
 
   pull_request:
     types: [opened, synchronize, reopened]
@@ -19,18 +22,35 @@ on:
       - 'trento-docs-site/package.json'
       - 'trento-docs-site/package-lock.json'
       - '.github/workflows/extension-tests.yaml'
+      - 'versions.yml'
+      - '.tool-versions'
+      - 'scripts/**'
 
   workflow_dispatch:
 
 jobs:
+  prepare:
+    runs-on: ubuntu-24.04
+    outputs:
+      node_image: ${{ steps.read-image.outputs.image }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Read Node.js image from versions.yml
+        id: read-image
+        run: echo "image=$(scripts/check-node-version.sh image)" >> "$GITHUB_OUTPUT"
+
   test-extensions:
+    needs: prepare
     runs-on: ubuntu-24.04
-    # openSUSE-based SUSE BCI image with Node.js 24 preinstalled
+    # SUSE BCI image taken from versions.yml, the same one docker-compose.yml uses
     container:
-      image: registry.suse.com/bci/nodejs:24
+      image: ${{ needs.prepare.outputs.node_image }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Check the Node.js version against .tool-versions
+        run: scripts/check-node-version.sh
       - name: Install dependencies
         working-directory: trento-docs-site
         run: npm ci --no-audit --no-fund

README.adoc

@@ -2,7 +2,7 @@
 ifndef::site-gen-antora[:relfileprefix: /content/]
 
 This repository is the central documentation source for the Trento project.
-It brings together multiple documentation sources and publishes them to the link:https://www.trento-project.io/docs/[Trento documentation hub] and the official user-facing SUSE documentation at link:https://documentation.suse.com/de-de/sles-sap/trento/[documentation.suse.com].
+It brings together multiple documentation sources and publishes them to the link:https://www.trento-project.io/docs/[Trento documentation hub] and the official user-facing SUSE documentation at link:https://documentation.suse.com/sles-sap/trento/[documentation.suse.com].
 
 == Repository Overview
 
@@ -107,6 +107,37 @@ Examples:
 ** link:https://github.com/trento-project/web/tree/main/guides[`trento-project/web/guides`]
 ** link:https://github.com/trento-project/agent/tree/main/docs[`trento-project/agent/docs`]
 
+=== Node.js version
+
+The Node.js version is defined once and reused everywhere:
+
+* link:https://github.com/trento-project/docs/blob/main/versions.yml[`versions.yml`] holds the container image. `docker-compose.yml` imports it with `extends`, so all container services run the same image, and the CI workflows read it into their job container.
+* link:https://github.com/trento-project/docs/blob/main/.tool-versions[`.tool-versions`] holds the same version for the local toolchain (`asdf`, `mise`).
+
+`scripts/check-node-version.sh` keeps the two in sync.
+It runs when each container starts and as a CI step, and fails the build if `versions.yml`, `.tool-versions`, and the running Node.js do not all agree:
+
+[source,bash]
+----
+scripts/check-node-version.sh
+----
+
+To see the newest image tag published in `registry.suse.com`:
+
+[source,bash]
+----
+scripts/check-node-version.sh latest
+----
+
+To upgrade Node.js, set the new version in both `versions.yml` and `.tool-versions`.
+
+To try another version without editing any file, override the tag:
+
+[source,bash]
+----
+CONTAINER_IMAGE_TAG=24.18.0 docker compose up trento-docs
+----
+
 === Preview the Trento docs hub
 
 From the repository root, this is the default way to preview the full docs hub workflow, including the current site assembly and published-output structure:

docker-compose.yml

@@ -1,8 +1,13 @@
 # SPDX-FileCopyrightText: SUSE LLC
 # SPDX-License-Identifier: Apache-2.0
 
+# Every Node.js service imports the image from versions.yml, so they all run the
+# same Node.js and none of them can pin a different one. Each service verifies
+# on start that the image matches .tool-versions.
 x-node-base: &node-base
-  image: registry.suse.com/bci/nodejs:24-base
+  extends:
+    file: versions.yml
+    service: node
 
 x-http-health: &http-health
   interval: 5s
@@ -19,6 +24,7 @@ services:
       - trento-docs-node-modules:/workspace/trento-docs-site/node_modules
     command: >
       bash -lc "
+        /workspace/scripts/check-node-version.sh &&
         npm ci &&
         npx antora antora-playbook.yml
       "
@@ -31,6 +37,7 @@ services:
       - .:/workspace:z
     command: >
       bash -lc "
+        /workspace/scripts/check-node-version.sh &&
         npx --yes http-server build/trento-docs-site-public/ -c-1 -p 3000
       "
     ports:
@@ -61,8 +68,15 @@ services:
       - "${PORT:-3001}:3001"
     volumes:
       - ./trento/build/SLES-SAP-trento/html/SLES-SAP-trento:/srv:ro
+      # Only what the version check needs; the repository is not mounted here
+      - ./scripts:/workspace/scripts:ro
+      - ./versions.yml:/workspace/versions.yml:ro
+      - ./.tool-versions:/workspace/.tool-versions:ro
     command: >
-      bash -lc "npx --yes http-server /srv -c-1 -p 3001"
+      bash -lc "
+        /workspace/scripts/check-node-version.sh &&
+        npx --yes http-server /srv -c-1 -p 3001
+      "
     depends_on:
       suse-daps-build:
         condition: service_completed_successfully
@@ -77,8 +91,15 @@ services:
       - "${PORTPDF:-3002}:3002"
     volumes:
       - ./trento/build/SLES-SAP-trento/:/srv:ro
+      # Only what the version check needs; the repository is not mounted here
+      - ./scripts:/workspace/scripts:ro
+      - ./versions.yml:/workspace/versions.yml:ro
+      - ./.tool-versions:/workspace/.tool-versions:ro
     command: >
-      bash -lc "npx --yes http-server /srv -c-1 -p 3002"
+      bash -lc "
+        /workspace/scripts/check-node-version.sh &&
+        npx --yes http-server /srv -c-1 -p 3002
+      "
     depends_on:
       suse-daps-build:
         condition: service_completed_successfully