enhancement: optimize Docker image build and runtime footprint (#4604)

* docker: add libgl1 runtime dependency for OpenGL

* docker: tighten .dockerignore for smaller build context

* docs(docker): add runtime notes for latest image

* docs(docker): note ctex is not included by default

---------

Co-authored-by: Francisco Manríquez Novoa <49853152+chopan050@users.noreply.github.com>

.dockerignore

@@ -1 +1,20 @@
 .git
+
+# Development / test artifacts
+__pycache__
+**/__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.egg-info
+dist/
+build/
+coverage.xml
+
+# Not needed to install the package
+docs/
+tests/
+example_scenes/
+media/
+logo/
+scripts/

docker/Dockerfile

@@ -1,42 +1,74 @@
-FROM python:3.11-slim
+# ── Stage 1: builder ─────────────────────────────────────────────────────────
+FROM python:3.14-slim AS builder
 
 RUN apt-get update -qq \
     && apt-get install --no-install-recommends -y \
         build-essential \
         gcc \
         cmake \
+        make \
+        pkg-config \
+        wget \
         libcairo2-dev \
         libffi-dev \
         libpango1.0-dev \
-        freeglut3-dev \
-        ffmpeg \
-        pkg-config \
-        make \
-        wget \
+        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 . /opt/manim
+WORKDIR /opt/manim
+RUN pip install --no-cache-dir .[jupyterlab]
+
+# ── Stage 2: runtime ─────────────────────────────────────────────────────────
+FROM python:3.14-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 \
+        libcairo2 \
+        libpango-1.0-0 \
+        libpangocairo-1.0-0 \
+        libpangoft2-1.0-0 \
+        libffi8 \
+        libegl1 \
+        libgl1 \
         ghostscript \
-        fonts-noto
+        fonts-noto-core \
+        fontconfig \
+    && rm -rf /var/lib/apt/lists/*
 
 RUN fc-cache -fv
 
-# setup a minimal texlive installation
-COPY docker/texlive-profile.txt /tmp/
+# 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
-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 ctex 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
+COPY --from=builder /usr/local/texlive /usr/local/texlive
 
-# clone and build manim
-COPY . /opt/manim
-WORKDIR /opt/manim
-RUN pip install --no-cache .[jupyterlab]
-
-RUN pip install -r docs/requirements.txt
+# 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"
 
 ARG NB_USER=manimuser
 ARG NB_UID=1000
@@ -49,11 +81,8 @@ RUN adduser --disabled-password \
     --uid ${NB_UID} \
     ${NB_USER}
 
-# create working directory for user to mount local directory into
 WORKDIR ${HOME}
-USER root
-RUN chown -R ${NB_USER}:${NB_USER} ${HOME}
-RUN chmod 777 ${HOME}
+RUN chown -R ${NB_USER}:${NB_USER} ${HOME} && chmod 777 ${HOME}
 USER ${NB_USER}
 
-CMD [ "/bin/bash" ]
+CMD ["/bin/bash"]

docker/readme.md

@@ -13,3 +13,11 @@ Multi-platform builds are possible by running
 docker buildx build --push --platform linux/arm64/v8,linux/amd64 --tag manimcommunity/manim:TAG -f docker/Dockerfile .
 ```
 from the root directory of the repository.
+
+# 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`.
+- Headless OpenGL rendering relies on EGL/GL runtime libraries available in the
+  image.

docs/source/installation/docker.rst

@@ -18,6 +18,13 @@ For our image ``manimcommunity/manim``, there are the following tags:
    ``-p`` (preview file) and ``-f`` (show output file in the file browser)
    are not supported.
 
+.. note::
+
+   The Docker image ships with a minimal TeX Live installation. In particular,
+   ``ctex`` is not installed by default. If your scenes rely on
+   ``TexTemplateLibrary.ctex``, install it in the container via
+   ``tlmgr install ctex``.
+
 
 Basic usage of the Docker container
 -----------------------------------