fix: switch Dockerfile base image from python:3.13 to ubuntu:24.04

[Copilot]

build-pdf CI fails on self-hosted runners because python:3.13 is Debian 13 ("Trixie")-based, and actions/setup-python has no toolcache binaries for that OS. Switching to ubuntu:24.04 aligns the container OS with GitHub-hosted runners, where the toolcache entry exists.

Changes to .devcontainer/Dockerfile

• FROM python:3.13 → FROM ubuntu:24.04
• Added python3 python3-pip python3-venv to apt-get install (Ubuntu doesn't bundle Python like the python: image does)

FROM ubuntu:24.04
...
    && apt-get -y install --no-install-recommends \
        ca-certificates curl gnupg2 git lsb-release nano make \
        unzip wget \
        python3 python3-pip python3-venv \
        latexmk texlive-fonts-extra ...

No changes to .github/workflows/sphinxbuild.yml.

☑️ Resolves

🖼️ Screenshots

✅ Checklist

• I have built the documentation locally and reviewed the output
• Screenshots are included for visual changes
• I have not moved or renamed pages (or added a redirect if I did)
• I have run codespell or similar and addressed any spelling issues

Original prompt

Problem

The build-pdf CI job fails on self-hosted runners with:

Version 3.13 was not found in the local cache
The version '3.13' with architecture 'x64' was not found for Debian 13.

This happens because the current .devcontainer/Dockerfile uses FROM python:3.13, which is based on Debian 13 ("Trixie"). When actions/setup-python runs inside this container, it tries to find a pre-built Python 3.13 binary for Debian 13 in the toolcache manifest — which doesn't exist. It works on official GitHub-hosted runners due to differences in how the runner resolves the container OS.

Fix

Switch the Dockerfile base image from python:3.13 to ubuntu:24.04 to match the GitHub-hosted runner OS. This ensures actions/setup-python can find its toolcache binaries for Python 3.13 on Ubuntu 24.04, making it work identically on both self-hosted and official runners.

Changes to make

Update .devcontainer/Dockerfile:

1. Change FROM python:3.13 → FROM ubuntu:24.04
2. Add python3 python3-pip python3-venv to the apt-get install list (since Ubuntu doesn't bundle Python like the python: image does)
3. Keep everything else (LaTeX packages, pip.conf, labels) exactly the same

The result should look like:

FROM ubuntu:24.04

LABEL org.opencontainers.image.source="https://github.com/nextcloud/documentation"
LABEL org.opencontainers.image.description="Sphinx build environment for Nextcloud documentation"
LABEL org.opencontainers.image.licenses="AGPL-3.0"

USER root

# Add dev tools needed for building
RUN export DEBIAN_FRONTEND=noninteractive \
    && apt-get update \
    && apt-get -y install --no-install-recommends \
        ca-certificates curl gnupg2 git lsb-release nano make \
        unzip wget \
        python3 python3-pip python3-venv \
        latexmk texlive-fonts-extra texlive-fonts-extra-links texlive-fonts-recommended \
        texlive-latex-extra texlive-latex-recommended tex-gyre texlive-xetex xindy \
    && mktexlsr \
    && rm -rf /var/lib/apt/lists/*

# Allow pip to install packages system-wide inside the container when running
# as root (avoids PEP 668 "externally managed environment" error)
RUN printf '[global]\nbreak-system-packages = true\n' > /etc/pip.conf

No changes are needed to .github/workflows/sphinxbuild.yml.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: https://github.com/nextcloud/documentation/actions/runs/24979411774/job/73188827584?pr=14182 fails pdf build on our own runners (which is supposedly mimicking the official gh runners)
But on official gh runners, it works
https://github.com/nextcloud/documentation/actions/runs/24989884443/job/73259325155?pr=14652

Assistant: The root cause is clear. Here's the breakdown:

---

Root Cause

The build-pdf job runs inside a Docker container based on python:3.13 (which is a Debian 13 "Trixie"-based image). When actions/setup-python runs inside that container, it reads the container's OS and tries to find a pre-compiled Python 3.13 binary for Debian 13 in the actions/python-versions manifest — and it doesn't exist there yet.

On the official GitHub-hosted runners, the job apparently runs differently (the passing job log shows it getting through to image-copy steps, suggesting it's potentially running without that container, or that runner environment handles it differently).

---

The Fix

Since your python:3.13 Docker image already has Python 3.13 installed, you don't need actions/setup-python at all in the build-pdf job. Remove it and use the Python already baked into the container:

      - name: Set up Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.13"
          # pip cache is not compatible with the Docker container
          # cache: "pip"

      - name: Install pip dependencies
        run: python -m pip install -r requirements.txt

Replace those steps with just:

      - name: Install pip dependencies
        run: python -m pip install -r requirements.txt

The python:3.13 base image already provides both python and pip, so actions/setup-python is redundant here and actively breaks on self-hosted runners whose Docker daemon reports the container OS as Debian 13 (which lacks pre-built toolcache binaries).

---

Why it works on official runners but not yours: This is likely a version difference in how the runner resolves the container OS label or a subtle difference in the Docker runtime reporting. Either way, the fix (dropping setup-python inside the container) is the correct long-term solution regardless.

Us...

This pull request was created from Copilot chat.

[skjnldsv]

To be closer to official GH runners so we can use the setup python properly.
Fails: https://github.com/nextcloud/documentation/actions/runs/24979411774/job/73188827584?pr=14182
Works: https://github.com/nextcloud/documentation/actions/runs/24989884443/job/73259325155?pr=14652

[DerDreschner]

@skjnldsv: This PR leads the devcontainer unusable for daily development as Ubuntu 24.04 comes with Python 3.12 while the requirement of the dependencies is 3.13 now. Switch to Ubuntu 26.04 instead and resolve the dependency conflict between python3-packaging v26.0 installed by apt repo in 26.04 and packaging==26.1 from requirements.txt.

root@15e0ce76e636:/IdeaProjects/documentation# aptitude why python3-packaging
i   python3-pip   Depends python3-wheel            
i A python3-wheel Depends python3-packaging (>= 24)
root@15e0ce76e636:/IdeaProjects/documentation# 

There's no php being installed now as well which breaks the composer install command in postCreateCommand.

[skjnldsv]

@skjnldsv: This PR leads the devcontainer unusable for daily development as Ubuntu 24.04 comes with Python 3.12 while the requirement of the dependencies is 3.13 now. Switch to Ubuntu 26.04 instead and resolve the dependency conflict between python3-packaging v26.0 installed by apt repo in 26.04 and packaging==26.1 from requirements.txt.

root@15e0ce76e636:/IdeaProjects/documentation# aptitude why python3-packaging
i   python3-pip   Depends python3-wheel            
i A python3-wheel Depends python3-packaging (>= 24)
root@15e0ce76e636:/IdeaProjects/documentation# 

There's no php being installed now as well which breaks the composer install command in postCreateCommand.

Thanks, I might have been on the wrong branch when I tested it then. Because it was fine for me. I'll have a look later ☺️

[DerDreschner]

@skjnldsv: As you were busy, I've tried to fix it myself in #14875. Hope my approach is okay. 😄