Using lsst-texmf with Docker

Besides installing lsst-texmf on your computer, you can compile lsst-texmf-based documents with Docker. This setup is useful for continuous integration environments since it avoids having to re-install TeX Live and lsst-texmf in each build. A Docker workflow is also useful for local writing since it turns lsst-texmf installation and document compilation into a single command. There’s no need to worry about installing LaTeX dependencies and setting a TEXMFHOME environment variable.

Quick start

To get started, you’ll need to install Docker.

Then from your LaTeX document’s directory, run:

docker run --rm -v `pwd`:/build -w /build lsstsqre/lsst-texmf:latest sh -c 'make'

Here’s what’s happening:

  • docker run downloads the Docker image (if necessary) and runs a container.
  • --rm removes the container once the run completes.
  • lsstsqre/lsst-texmf:latest is the name of the Docker image. This tracks the master branch of the lsst-texmf GitHub repository.
  • -v `pwd`:/build binds the current directory (containing your document) into the /build directory in the container
  • -w /build makes the bound volume the working directory in the container.
  • sh -c 'make' is the command that’s run from the container’s working directory to compile your document. The example uses a Makefile, but this command can be customized for your project.
  • The compiled PDF is written into the current directory on your computer since it was bound to the container.

Deleting or refreshing the Docker image

Once downloaded, Docker caches the lsstsqre/lsst-texmf:latest image on your computer. If lsst-texmf is updated, you can refresh your image by deleting the cached copy:

docker rmi lsstsqre/lsst-texmf:latest

The next time you docker run the new lsst-texmf:latest image will be downloaded.

About the lsst-texmf Docker image

The lsstsqre/lsst-texmf Docker image is based on the python:3.7-slim-buster (Debian) official Docker image. Using a Python base image ensures the correct version of Python is available for lsst-texmf’s Python scripts.

System packages

The Docker image contains a TeX Live distribution, as well as several utilities. See the docker/install-base-packages.sh script in the lsst-texmf repository for the current list of installed packages.

Scripts and Python dependencies

Inside the Docker container, lsst-texmf’s bin directory is included in the PATH environment variable. You can call scripts such as generateAcronyms.py and db2authors.py from your document’s Makefile directly.

The Docker image also includes Python packages needed for lsst-texmf’s scripts, as well as scripts that might be run as part of your document’s Makefile. See the requirements.txt file in the lsst-texmf repository for the current list of installed Python packages.