A community-maintained Python framework for creating mathematical animations.
Make Docker image build robust against TeX mirror failures (#5095)
Benjamin Hackl78d47aec8c81
diff --git a/.dockerignore b/.dockerignoreindex e19bacca9..73dc71e52 100644--- a/.dockerignore+++ b/.dockerignore@@ -1,6 +1,8 @@.git# Development / test artifacts+.venv+.pytest_cache__pycache__**/__pycache__*.pycdiff --git a/.github/workflows/publish-docker.yml b/.github/workflows/publish-docker.ymlindex 19bb4bb57..05f79ecc4 100644--- a/.github/workflows/publish-docker.yml+++ b/.github/workflows/publish-docker.yml@@ -6,39 +6,118 @@ on:- mainrelease:types: [released]+ pull_request:+ paths:+ - docker/**+ - .dockerignore+ - .github/workflows/publish-docker.yml+ workflow_dispatch:++# A newer push to main supersedes an older build still in progress, so an+# outdated build can never overwrite `latest`.+concurrency:+ group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}+ cancel-in-progress: true++permissions:+ contents: read++env:+ IMAGE: manimcommunity/manim+ # Only pushes to main and releases publish to Docker Hub. Pull requests and+ # manual runs on other branches only build and verify the image.+ PUBLISH: ${{ github.event_name == 'release' || (github.event_name != 'pull_request' && github.ref == 'refs/heads/main') }}jobs:- docker-latest:- runs-on: ubuntu-latest- if: github.event_name != 'release'+ build:+ name: Build (${{ matrix.arch }})+ runs-on: ${{ matrix.runner }}+ timeout-minutes: 60+ strategy:+ fail-fast: true+ matrix:+ include:+ - arch: amd64+ platform: linux/amd64+ runner: ubuntu-24.04+ - arch: arm64+ platform: linux/arm64+ runner: ubuntu-24.04-armsteps:- - name: Set up QEMU- uses: docker/setup-qemu-action@v4+ - name: Checkout+ uses: actions/checkout@v7- name: Set up Docker Buildxuses: docker/setup-buildx-action@v4- name: Login to DockerHub+ if: env.PUBLISH == 'true'uses: docker/login-action@v4with:username: ${{ secrets.DOCKERHUB_USERNAME }}password: ${{ secrets.DOCKERHUB_TOKEN }}- - name: Build and push+ - name: Build image+ uses: docker/build-push-action@v7+ with:+ context: .+ file: docker/Dockerfile+ platforms: ${{ matrix.platform }}+ load: true+ tags: manim:verify+ cache-from: type=gha,scope=docker-${{ matrix.arch }}+ # Only publishing builds write the cache, so pull requests do not+ # evict the cache that main and releases rely on.+ cache-to: ${{ env.PUBLISH == 'true' && format('type=gha,scope=docker-{0},mode=max', matrix.arch) || '' }}++ - name: Verify image+ run: |+ docker run --rm -v "$PWD/docker:/test:ro" manim:verify \+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage++ # Reuses the layers built above; pushes an untagged image by digest.+ # The publish job tags the per-platform digests as one image.+ - name: Push image by digest+ id: push+ if: env.PUBLISH == 'true'uses: docker/build-push-action@v7with:- platforms: linux/arm64,linux/amd64- push: true+ context: .file: docker/Dockerfile- tags: |- manimcommunity/manim:latest+ platforms: ${{ matrix.platform }}+ outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true+ cache-from: type=gha,scope=docker-${{ matrix.arch }}- docker-release:+ - name: Export digest+ if: env.PUBLISH == 'true'+ env:+ DIGEST: ${{ steps.push.outputs.digest }}+ run: |+ mkdir -p "$RUNNER_TEMP/digests"+ touch "$RUNNER_TEMP/digests/${DIGEST#sha256:}"++ - name: Upload digest+ if: env.PUBLISH == 'true'+ uses: actions/upload-artifact@v7+ with:+ name: digest-${{ matrix.arch }}+ path: ${{ runner.temp }}/digests/*+ if-no-files-found: error+ retention-days: 1++ publish:+ name: Publish multi-platform image+ needs: build+ if: github.event_name == 'release' || (github.event_name != 'pull_request' && github.ref == 'refs/heads/main')runs-on: ubuntu-latest- if: github.event_name == 'release'+ timeout-minutes: 15steps:- - name: Set up QEMU- uses: docker/setup-qemu-action@v4+ - name: Download digests+ uses: actions/download-artifact@v8+ with:+ path: ${{ runner.temp }}/digests+ pattern: digest-*+ merge-multiple: true- name: Set up Docker Buildxuses: docker/setup-buildx-action@v4@@ -49,24 +128,15 @@ jobs:username: ${{ secrets.DOCKERHUB_USERNAME }}password: ${{ secrets.DOCKERHUB_TOKEN }}- - name: Get Version- id: create_release- shell: python- env:- tag_act: ${{ github.ref }}+ - name: Create and push manifest list+ working-directory: ${{ runner.temp }}/digestsrun: |- import os- ref_tag = os.getenv('tag_act').split('/')[-1]- with open(os.getenv('GITHUB_OUTPUT'), 'w') as f:- print(f"tag_name={ref_tag}", file=f)+ tags=(-t "$IMAGE:latest")+ if [ "$GITHUB_EVENT_NAME" = release ]; then+ tags+=(-t "$IMAGE:stable" -t "$IMAGE:$GITHUB_REF_NAME")+ fi+ docker buildx imagetools create "${tags[@]}" \+ $(printf "$IMAGE@sha256:%s " *)- - name: Build and push- uses: docker/build-push-action@v7- with:- platforms: linux/arm64,linux/amd64- push: true- file: docker/Dockerfile- tags: |- manimcommunity/manim:stable- manimcommunity/manim:latest- manimcommunity/manim:${{ steps.create_release.outputs.tag_name }}+ - name: Inspect image+ run: docker buildx imagetools inspect "$IMAGE:latest"diff --git a/docker/Dockerfile b/docker/Dockerfileindex 7036c754a..463f1e28a 100644--- a/docker/Dockerfile+++ b/docker/Dockerfile@@ -1,52 +1,113 @@-# ── Stage 1: builder ─────────────────────────────────────────────────────────-FROM python:3.14-slim AS builder+# syntax=docker/dockerfile:1-RUN apt-get update -qq \- && apt-get install --no-install-recommends -y \+ARG PYTHON_VERSION=3.14+ARG UV_VERSION=0.13+# TeX Live is pinned to the frozen final state of a past release ("tlnet-final"+# in the historic archive), so the installation is identical on every build and+# does not depend on the CTAN mirror rotation.+ARG TL_YEAR=2025++FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv++# ── Stage 1: TeX Live ────────────────────────────────────────────────────────+# Independent of the Python base image and of the manim sources, so the build+# cache for this (network-heavy) stage survives most changes.+FROM debian:trixie-slim AS texlive++ARG TL_YEAR+# Tried in order; the first repository that completes the installation wins.+ARG TL_REPOSITORIES="\+https://ftp.tu-chemnitz.de/pub/tug/historic/systems/texlive/${TL_YEAR}/tlnet-final \+https://mirrors.tuna.tsinghua.edu.cn/tex-historic-archive/systems/texlive/${TL_YEAR}/tlnet-final"++RUN apt-get -o Acquire::Retries=5 update -qq \+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \+ ca-certificates \+ curl \+ libfontconfig1 \+ perl \+ xz-utils \+ && rm -rf /var/lib/apt/lists/*++COPY docker/texlive-profile.txt docker/texlive-packages.txt /tmp/++# bin/linux is an architecture-independent link to bin/{x86_64,aarch64}-linux.+RUN set -eu; \+ packages="$(grep -v -e '^#' -e '^[[:space:]]*$' /tmp/texlive-packages.txt)"; \+ for repo in ${TL_REPOSITORIES}; do \+ echo "==> Installing TeX Live ${TL_YEAR} from ${repo}"; \+ rm -rf /tmp/install-tl /usr/local/texlive; \+ mkdir -p /tmp/install-tl; \+ if curl -fsSL --retry 5 --retry-all-errors --connect-timeout 20 --max-time 300 \+ -o /tmp/install-tl-unx.tar.gz "${repo}/install-tl-unx.tar.gz" \+ && tar -xzf /tmp/install-tl-unx.tar.gz -C /tmp/install-tl --strip-components=1 \+ && timeout 30m /tmp/install-tl/install-tl \+ --profile=/tmp/texlive-profile.txt --repository "${repo}" \+ && timeout 30m /usr/local/texlive/bin/*-linux/tlmgr \+ --repository "${repo}" install ${packages}; \+ then \+ installed=1; \+ break; \+ fi; \+ echo "==> Installation from ${repo} failed, trying the next repository" >&2; \+ done; \+ test "${installed:-0}" = 1 || { echo "==> All TeX Live repositories failed" >&2; exit 1; }; \+ ln -s "$(basename /usr/local/texlive/bin/*-linux)" /usr/local/texlive/bin/linux; \+ rm -rf /tmp/install-tl /tmp/install-tl-unx.tar.gz \+ /usr/local/texlive/install-tl.log /usr/local/texlive/texmf-var/web2c/*.log++ENV PATH=/usr/local/texlive/bin/linux:$PATH+RUN latex --version | head -n 1 && dvisvgm --version++# ── Stage 2: Python builder ──────────────────────────────────────────────────+FROM python:${PYTHON_VERSION}-slim AS builder++RUN apt-get -o Acquire::Retries=5 update -qq \+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \build-essential \- gcc \cmake \- make \pkg-config \- wget \libcairo2-dev \libffi-dev \libpango1.0-dev \libegl-dev \&& rm -rf /var/lib/apt/lists/*-# Setup a minimal TeX Live installation (no ctex: drops ~100 MB of CJK fonts/packages)-COPY docker/texlive-profile.txt /tmp/-ENV PATH=/usr/local/texlive/bin/armhf-linux:/usr/local/texlive/bin/aarch64-linux:/usr/local/texlive/bin/x86_64-linux:$PATH-RUN wget -O /tmp/install-tl-unx.tar.gz http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz \- && mkdir /tmp/install-tl \- && tar -xzf /tmp/install-tl-unx.tar.gz -C /tmp/install-tl --strip-components=1 \- && /tmp/install-tl/install-tl --profile=/tmp/texlive-profile.txt \- && tlmgr install \- amsmath babel-english cbfonts-fd cm-super count1to doublestroke dvisvgm everysel \- fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin \- mathastext microtype multitoc physics prelim2e preview ragged2e relsize rsfs \- setspace standalone tipa wasy wasysym xcolor xetex xkeyval \- && rm -rf /tmp/install-tl /tmp/install-tl-unx.tar.gz--# Install manim into an isolated virtualenv-ENV VIRTUAL_ENV=/opt/venv-RUN python -m venv $VIRTUAL_ENV-ENV PATH="$VIRTUAL_ENV/bin:$PATH"+COPY --from=uv /uv /usr/local/bin/uv++ENV UV_COMPILE_BYTECODE=1 \+ UV_LINK_MODE=copy \+ UV_PYTHON=/usr/local/bin/python3 \+ UV_PYTHON_DOWNLOADS=never \+ UV_PROJECT_ENVIRONMENT=/opt/venv-COPY . /opt/manimWORKDIR /opt/manim-RUN pip install --no-cache-dir .[jupyterlab]-# ── Stage 2: runtime ─────────────────────────────────────────────────────────-FROM python:3.14-slim+# Third-party dependencies, pinned by uv.lock. This layer is only rebuilt when+# pyproject.toml or uv.lock change, not on every change to the manim sources.+RUN --mount=type=cache,target=/root/.cache/uv \+ --mount=type=bind,source=uv.lock,target=uv.lock \+ --mount=type=bind,source=pyproject.toml,target=pyproject.toml \+ uv sync --locked --no-dev --no-install-project --extra jupyterlab++# manim itself (non-editable, so the sources are not needed at runtime).+# pip is added to the virtualenv from the bundled wheel (no download), so that+# derived images can still `pip install` plugins.+COPY . /opt/manim+RUN --mount=type=cache,target=/root/.cache/uv \+ uv sync --locked --no-dev --no-editable --extra jupyterlab \+ && /opt/venv/bin/python -m ensurepip \+ && /opt/venv/bin/manim --version++# ── Stage 3: runtime ─────────────────────────────────────────────────────────+FROM python:${PYTHON_VERSION}-slim# Runtime libs only:# - no ffmpeg: PyAV (av package) bundles its own ffmpeg libraries in av.libs/# - OpenGL: keep EGL for headless rendering and libGL as required by moderngl/glcontext# - fonts-noto-core instead of fonts-noto (drops CJK noto fonts)-RUN apt-get update -qq \- && apt-get install --no-install-recommends -y \+RUN apt-get -o Acquire::Retries=5 update -qq \+ && apt-get -o Acquire::Retries=5 install --no-install-recommends -y \libcairo2 \libpango-1.0-0 \libpangocairo-1.0-0 \@@ -57,32 +118,30 @@ RUN apt-get update -qq \ghostscript \fonts-noto-core \fontconfig \- && rm -rf /var/lib/apt/lists/*--RUN fc-cache -fv--# Copy TeX Live from builder-ENV PATH=/usr/local/texlive/bin/armhf-linux:/usr/local/texlive/bin/aarch64-linux:/usr/local/texlive/bin/x86_64-linux:$PATH-COPY --from=builder /usr/local/texlive /usr/local/texlive--# Copy the pre-built virtualenv from builder-ENV VIRTUAL_ENV=/opt/venv-COPY --from=builder /opt/venv /opt/venv-ENV PATH="$VIRTUAL_ENV/bin:$PATH"+ && rm -rf /var/lib/apt/lists/* \+ && fc-cache -fARG NB_USER=manimuserARG NB_UID=1000-ENV USER=${NB_USER}-ENV NB_UID=${NB_UID}-ENV HOME=/manim+ENV USER=${NB_USER} \+ NB_UID=${NB_UID} \+ HOME=/manimRUN adduser --disabled-password \- --gecos "Default user" \- --uid ${NB_UID} \- ${NB_USER}+ --gecos "Default user" \+ --uid ${NB_UID} \+ ${NB_USER} \+ && mkdir -p ${HOME} \+ && chown -R ${NB_USER}:${NB_USER} ${HOME} \+ && chmod 777 ${HOME}++COPY --from=texlive /usr/local/texlive /usr/local/texlive+COPY --from=builder /opt/venv /opt/venv++ENV VIRTUAL_ENV=/opt/venv \+ PATH=/opt/venv/bin:/usr/local/texlive/bin/linux:$PATHWORKDIR ${HOME}-RUN chown -R ${NB_USER}:${NB_USER} ${HOME} && chmod 777 ${HOME}USER ${NB_USER}CMD ["/bin/bash"]diff --git a/docker/readme.md b/docker/readme.mdindex 8c5ccc383..b45faf63c 100644--- a/docker/readme.md+++ b/docker/readme.md@@ -14,10 +14,27 @@ docker buildx build --push --platform linux/arm64/v8,linux/amd64 --tag manimcomm```from the root directory of the repository.+To check a built image, render the verification scene (LaTeX, XeLaTeX, Pango, video encoding):+```+docker run --rm -v "$PWD/docker:/test:ro" manimcommunity/manim:TAG \+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage+```++# Build notes+- The image is built via a multi-stage Dockerfile: TeX Live, the Python+ virtualenv and the runtime image are separate stages, and build dependencies+ are not carried into the runtime stage.+- TeX Live is pinned to the frozen final state of a past release (`TL_YEAR`)+ from the TeX Live historic archive, with fallback mirrors (`TL_REPOSITORIES`).+ Bump `TL_YEAR` once the next release is frozen. TeX packages are listed in+ `texlive-packages.txt`.+- Python dependencies are installed from `uv.lock`.+- CI builds each platform on a native runner and caches layers, so the TeX+ Live stage is usually not rebuilt.+# Runtime notes-- The image is built via a multi-stage Dockerfile (build dependencies are not- carried into the runtime stage).- The image does not include the `ffmpeg` CLI binary.- The default TeX installation is minimal and does not include `ctex`.+ `tlmgr` installs further packages from the same frozen TeX Live release.- Headless OpenGL rendering relies on EGL/GL runtime libraries available in theimage.diff --git a/docker/texlive-packages.txt b/docker/texlive-packages.txtnew file mode 100644index 000000000..b3af1bb9e--- /dev/null+++ b/docker/texlive-packages.txt@@ -0,0 +1,34 @@+# TeX Live packages installed on top of scheme-minimal (one per line).+# ctex is left out on purpose: it adds ~100 MB of CJK fonts and packages.+amsmath+babel-english+calligra+cbfonts-fd+cm-super+count1to+doublestroke+dvisvgm+everysel+fontspec+frcursive+fundus-calligra+gnu-freefont+jknapltx+latex-bin+mathastext+microtype+multitoc+physics+prelim2e+preview+ragged2e+relsize+rsfs+setspace+standalone+tipa+wasy+wasysym+xcolor+xetex+xkeyvaldiff --git a/docker/texlive-profile.txt b/docker/texlive-profile.txtindex 413b46a56..6e8450817 100644--- a/docker/texlive-profile.txt+++ b/docker/texlive-profile.txt@@ -6,5 +6,7 @@ TEXMFLOCAL /usr/local/texlive/texmf-localTEXMFSYSCONFIG /usr/local/texlive/texmf-configTEXMFSYSVAR /usr/local/texlive/texmf-varTEXMFVAR ~/.texlive/texmf-var-option_doc 0-option_src 0+instopt_adjustpath 0+tlpdbopt_autobackup 0+tlpdbopt_install_docfiles 0+tlpdbopt_install_srcfiles 0diff --git a/docker/verify_image.py b/docker/verify_image.pynew file mode 100644index 000000000..e4a71e153--- /dev/null+++ b/docker/verify_image.py@@ -0,0 +1,37 @@+"""Verification scene for the Docker image, rendered by the publish-docker workflow.++Covers LaTeX (default template, and the 3b1b template that loads most of the+bundled TeX packages), XeLaTeX with fontspec, dvisvgm, Pango text, and video+encoding via PyAV::++ docker run --rm -v "$PWD/docker:/test:ro" manimcommunity/manim:TAG \+ manim render -ql --media_dir /tmp/media /test/verify_image.py VerifyImage+"""++from manim import *++XELATEX = TexTemplate(+ tex_compiler="xelatex",+ output_format=".xdv",+ preamble=r"""+\usepackage{fontspec}+\usepackage{amsmath}+""",+)+++class VerifyImage(Scene):+ def construct(self):+ tex = MathTex(r"\int_0^1 x^2\,dx = \frac{1}{3}")+ packages = MathTex(+ r"\mathds{R} \quad \mathscr{L} \quad \dv{f}{x}",+ tex_template=TexTemplateLibrary.threeb1b,+ )+ # calligra is a METAFONT font, so this also checks on-demand font generation.+ calligra = Tex(+ r"{\calligra Calligra}", tex_template=TexTemplateLibrary.threeb1b+ )+ xetex = Tex(r"XeLaTeX: \textbf{fontspec}", tex_template=XELATEX)+ text = Text("Pango text")+ group = VGroup(tex, packages, calligra, xetex, text).arrange(DOWN)+ self.play(Write(group), run_time=0.5)