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 Ubuntu 14.04 (trusty). It contains a full TeX Live distribution, as well as make and git, via the lsstsqre/lsst-texlive image. The image also contains a Java runtime for acronyms.csh. lsst-texmf is installed in the container’s /texmf directory, with TEXMFHOME pre-set to that directory. Scripts from lsst-texmf’s /bin directory are available in the container’s PATH.

The latest tag tracks the master branch. Other tags may be available for pinned versions and development branches. See the list of tags on Docker Hub.

Usually you’ll want to use the latest tag.