docs agent's mkdocs build failed inside docker, missing system packages

TL;DR

Read the build log for the missing shared library or binary, add the system package to the Dockerfile, rebuild the image, and rerun the agent's docs build. Pin the package version so the environment stays reproducible.

The exact error

mkdocs build inside docker: missing system package error

Steps

1. Read the failure Open the agent's build log and find the missing library or command error, e.g. a missing font library for PDF export. Success check: You know the exact system package that is missing.

2. Add it to the Dockerfile Install the package with the image's package manager in the Dockerfile, before the pip install layer. Success check: The Dockerfile installs the system dependency.

3. Rebuild the image Build the image fresh (no stale cache on the changed layer) and confirm the package is present. Success check: The new image contains the system package.

4. Rerun the agent build Run the agent's mkdocs build inside the new image and confirm it completes. Success check: The docs build succeeds in the container.

When to use

• Use when a docs agent's containerized MkDocs build fails on system deps.
• Use when moving a working local docs build into Docker.

When not to use

• Not for Python package errors (pip dependency problem, not system).
• Not for mkdocs config errors (those fail identically outside Docker).

Why it happens

MkDocs plugins with native extensions (PDF export, image processing) need system libraries that slim Python images omit. A build that works on the agent's host fails in the container, and the error names the missing .so or binary.

Edge cases

Pinning the system package version matters because unpinned apt installs drift between image builds. Multi-stage builds can keep the final docs image small while the build stage carries the native toolchain.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7CjUEDmshgdf9eA3b7xI7g