Awesome

TeXlive Docker Images

Yet another attempt at coming up with working and generally applicable Docker images for TeXlive.

The basic concept is to provide small-ish base images which install additional packages from CTAN if and when needed.

These images attempt to cover the following use cases:

• Replace local TeXlive installations.
• Build LaTeX documents in CI/CD pipelines.
• Build legacy documents with old package versions.

We currently publish the following images based on different selections from the TeXlive collections suggested by the installer; from smaller to larger:

• reitzig/texlive-minimal (profile)
• reitzig/texlive-base (profile)
• reitzig/texlive-base-luatex (profile)

We also provide PoCs to demonstrate that more involved applications can be built on top of the base images provided here:

• Serve a static set of pre-built documents.

Usage

The fastest way to build a document at hand (once) is this:

docker run --rm \
    --volume `pwd`:/work/src:ro \
    --volume `pwd`/out:/work/out \
    reitzig/texlive-base-luatex \
    work lualatex hello_world.tex

Note:

• This assumes that all TeXlive packages beyond what is contained in the texlive-base-luatex image are listed in Texlivefile. You can also use image reitzig/texlive-full instead if you are happy with downloading a (way) larger image.
• This may overwrite files in out. Chose a folder name that you currently do not use.

See the scripts in examples for other ways to use the images.

Dependencies

Place a file called Texlivefile with a list of required CTAN packages, one name per line, in the source directory. The container will install all packages on that list before running the work command.

⚠️ Installing dependencies in this way will stop working once a new version of TeXlive is released, with an error like this:

tlmgr: Local TeX Live (2023) is older than remote repository (2024).

If you need to keep using an older image for a little while, you can override the repository by setting environment variable TEXLIVE_REPOSITORY to a value like

https://ftp.math.utah.edu/pub/tex/historic/systems/texlive/2023/tlnet-final

This feature has been available since 2024.2; see reitzig/texlive-docker#18.2022953222 for hints on how to backport it to older images.

⚠️ Note that most CTAN mirrors do not maintain historic versions (cf. tex.SE#460132), so keep in mind that widespread use of this workaround will stress those few mirrors that do. We strongly recommend upgrading to the latest TeXlive version as soon as possible!

ℹ️ That said, an alternative is to maintain custom Docker images with historic package versions<!--; see [here](TODO) for an example-->. This approach completely avoids the need for running tlmgr at runtime, so repository freeze does not impact your builds.

Parameters

You can adjust some defaults of the main container script by setting environment variables

• BUILDSCRIPT (default: build.sh)
  If present, the given script will be executed unless a work command is specified.
• TEXLIVEFILE (default: Texlivefile)
  The file to read dependencies from.
• OUTPUT (default: *.pdf *.log)
  Shell pattern for all files that should be copied from the working to the output directory.

Debugging

All output of the work command is collected in a single folder; extract it with:

docker cp $container:/work/tmp ./

Build

Run

docker build -t texlive-base-luatex --build-arg "profile=base-luatex" .

to build an image locally. Exchange base-luatex for any of the profile names in profiles to start from another baseline.

Customization

If you repeatedly need the same exact set of dependencies or even sources, it might make sense to create your own TeXlive Docker image. There are two ways to go about that:

• Extend one of the existing images using your own Dockerfile (see example); install additional TeXlive (or even Alpine) packages, copy source files or additional scripts into the appropriate folders, fix the work command, or ...

• Use install-tl to create your own TeXlive installation profile. Make sure to

  1. select platform x86_64-linuxmusl and
  2. manually change line binary_x86_64-linux 1 in the resulting profile file to binary_x86_64-linux 0. <!-- Yup, it's a workaround; musl-only installs are apparently not well-supported. See a matching note in Dockerfile. Any advice is appreciated. -->

  If you want to use your profile across different TeXlive versions, replace all occurrences of the TeXlive version (e.g. 2019) with ${tlversion}.

  Copy the final file to profiles and run the regular build command.