chore(mr): prepare v2024.10.1 (#7)

- use official Docker image Ubuntu 24.04.1 LTS "Noble" with tag 20240904.1
  from https://hub.docker.com/_/ubuntu
- asdf-vm version 0.14.1 with updates from https://github.com/asdf-vm/asdf
- asdf-vm plugins for:
  - pipx:   https://github.com/yozachar/asdf-pipx
  - python: https://github.com/asdf-community/asdf-python
  - nodejs: https://github.com/asdf-vm/asdf-nodejs
  - rust:   https://github.com/code-lever/asdf-rust
  - golang: https://github.com/asdf-community/asdf-golang
  - ruby:   https://github.com/asdf-vm/asdf-ruby
- enable shell completions for PyPA pipx

Signed-off-by: Stephan Linz <[email protected]>

.github/workflows/docker-publish.yml

@@ -40,6 +40,13 @@ jobs:
       # with sigstore/fulcio when running outside of PRs.
       id-token: write
 
+    # Allow to build longer than 6 hours, but this is only possible
+    # with self-hosted runners. 1440 min = 24 h. For details, see:
+    # https://github.com/orgs/community/discussions/26679
+    # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+    # https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration
+    timeout-minutes: 1440
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -75,6 +82,12 @@ jobs:
         if: github.event_name != 'pull_request'
         run: cosign version
 
+      # Install QEMU static binaries for multi-arch image build
+      # https://github.com/docker/setup-qemu-action
+      # https://docs.docker.com/build/ci/github-actions/multi-platform
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
       # Set up BuildKit Docker container builder to be able to build
       # multi-platform images and export cache
       # https://github.com/docker/setup-buildx-action
@@ -107,6 +120,9 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
+          # HOTFIX: reduce build time to beeing under standard limit of
+          # 6 hours runtime ("timeout-minutes") on GitHub hosted runners.
+          platforms: linux/amd64
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

CONTRIBUTING.md

@@ -13,15 +13,52 @@ If you would like to fix a bug or add a feature to our build images, see
 ## Testing Locally
 
 If you'd like to add a feature to any of the images, you'll need to verify the
-image works locally first. After making changes to the ``Dockerfile``, you can
-build your image with:
+image works locally first. To build multi-platform images, you first need to
+make sure that your [Docker environment is set up to support it](
+https://docs.docker.com/build/building/multi-platform/#prerequisites),
+e.g. QEMU and a custom builder with self contained containerd image store.
+To create such a custom builder, use the ``docker buildx create`` command:
 
 ```bash
-docker build -t tiacsys/readourdocs-docker-images:local .
+docker buildx create --name rod-ctn-builder --driver docker-container \
+                     --bootstrap --use
 ```
 
-This will take quite a long time, mostly due to LaTeX dependencies. The
-resulting image will be at least around 12GB.
+After making changes to the ``Dockerfile``, you can build your image with:
+
+```bash
+docker buildx build --tag tiacsys/readourdocs-docker-images:local \
+                    --platform linux/amd64,linux/arm/v7,linux/arm64,linux/riscv64,linux/ppc64le,linux/s390x \
+                    --builder rod-ctn-builder --load .
+```
+
+**ERROR: docker exporter does not currently support exporting manifest lists**
+
+Unfortunately, it is impossible to run that multi-platform image as local
+container. Container images with support for multiple architectures are part of
+the [OCI specification](
+https://github.com/opencontainers/image-spec/blob/main/image-index.md) and
+Docker supports creating these as well. The image index (more commonly referred
+to as the image manifest) contains some metadata about the image itself and an
+array of actual manifests which specify the platform and the image layer
+references. Docker supports creating these but only through the experimental
+new builder, *buildx*.
+
+Buildx has some nice new features like support for better caching between
+images as well as cleaner output during builds. However, it runs completely
+independently of your standard local docker registry. If you run ``docker ps``,
+you’ll see a buildx builder running as a container on your local machine. This
+is a virtual builder that we created using ``docker buildx create``.
+
+**Simple build for native platform**
+
+```bash
+docker build --tag tiacsys/readourdocs-docker-images:local .
+```
+
+This will take quite a long time, mostly due to LaTeX dependencies and required
+rebuilds of components from source code for different platforms. The resulting
+images will be at least around 17GB.
 
 Once your image is built, you can test your image locally by running a shell in
 a container using your new image:
@@ -55,6 +92,8 @@ completely deleted at any time with:
 
 ```bash
 docker image rm tiacsys/readourdocs-docker-images:local
+docker buildx rm rod-ctn-builder
+docker buildx prune --all --force
 docker builder prune --all --force
 ```