reitzig / texlive-docker

Docker images for TeXlive that easily adjust to your needs

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. 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.

  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.

texlive-docker's Issues

Support easy installation of biber

Biber is installed there

/usr/local/texlive/2023/bin/x86_64-linuxmusl/biber

The path /usr/local/texlive/2023/bin/x86_64-linuxmusl should be added to the PATH.

Alternatively, if biber is installed via Texlivefile, following command should be executed:

cp /usr/local/texlive/2023/bin/x86_64-linuxmusl/biber /usr/local/bin

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

dockerfile

Dockerfile

• alpine 3.19@sha256:c5b1261d6d3e43071626931fc004f70149baeba2c8ec672bd4f27761f8e1ad6b

demo/static-document-server/Dockerfile

github-actions

.github/workflows/test-and-publish.yml

• actions/checkout v4
• actions/checkout v4
• actions/checkout v4

.github/workflows/trigger-release.yml

• actions/checkout v4

.github/workflows/update-dockerhub-info.yml

• actions/checkout v4

regex

Dockerfile

• alpine_3_19/bash 5.2.21-r0
• alpine_3_19/cairo 1.18.0-r0
• alpine_3_19/gpg 2.4.4-r0
• alpine_3_19/icu 74.1-r0
• alpine_3_19/gcc 13.2.1_git20231014-r0
• alpine_3_19/libpaper 2.1.2-r0
• alpine_3_19/libpng 1.6.40-r0
• alpine_3_19/gcc 13.2.1_git20231014-r0
• alpine_3_19/libx11 1.8.7-r0
• alpine_3_19/musl 1.2.4_git20230717-r4
• alpine_3_19/perl 5.38.2-r0
• alpine_3_19/pixman 0.42.2-r2
• alpine_3_19/wget 1.21.4-r0
• alpine_3_19/xz 5.4.5-r0
• alpine_3_19/zlib 1.3.1-r0

---

• Check this box to trigger a request for Renovate to run again on this repository

Image doesn't work anymore when using a Texlivefile now that TeXLive 2024 is out

The entrypoint now outputs:

Installing dependencies ...

tlmgr: Local TeX Live (2023) is older than remote repository (2024).
Cross release updates are only supported with
  update-tlmgr-latest(.sh/.exe) --update
See https://tug.org/texlive/upgrade.html for details.

There are two solutions to this:

• do update-tlmgr-latest.sh --update as suggested. However this will move to TeX Live 2024 which is probably not what we want in a build environment that should be somewhat reproducible.

• explicitly give the 2023 repository:

           repo="--repository https://ftp.math.utah.edu/pub/tex/historic/systems/texlive/2023/tlnet-final"
           tlmgr update $repo --self
           xargs tlmgr install $repo < "${SRC_DIR}/${TEXLIVEFILE}"
  

This seems desirable, however I didn't do a PR for this because there is an underlying question on how you want to deal with new TeX Live versions in general. For all I know, the shown repository solution can only be employed once the version has been frozen, so you can't simply release a 2024 image with an explicit repo to avoid this problem in the future.

It might be a good idea to do a check whether tlnet-final is available remotely and if so, fill the repo variable. I don't know TeX Live well enough to be content that this is the good solution.

Fix credentials for release workflow (to release 2023.1)

The monthly release automation fails, because

See https://github.com/reitzig/texlive-docker/actions/runs/4580266415/jobs/8088841313 for an example

Will try to create tag release-2023.1 on reitzig/texlive-docker:d2937841b944109856bb26bfdf85895f6a09bd0b

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

---

I should also write something now and then. Otherwise, workflows are not run due to inactivity:

gpg unavailable

tlmgr: package repository https://ctan.mirrors.hoobly.com/systems/texlive/tlnet (not verified: gpg unavailable)

Would it make sense to add gpg to texlive-base - or does it consume too much space?

Example: Maintain custom image for CI builds

Provide an example/demo for the "keep builds stable" scenario, using a custom image persisted to GHCR by a workflow.

re #18

Tools installed with tlmgr are not in PATH

When I have e.g. latexmk in my Texlivefile, I cannot call it after tlmgr installed it because it's not in the PATH.

I did a quick workaround in the entrypoint script by adding:

export PATH="${PATH}:/usr/local/texlive/2023/bin/x86_64-linuxmusl"

However this should likely be solved in a future-proof way.