This page contains documentation for the custom Docker container developed for facilitating the generation of LaTeX documents. This container is mainly designed for CI/CD pipelines, but can also be directly used from the command line prompt or as a backend for other middleware.


Distribution

The thesis/builder image is built on Debian stable and TeXLive distributions. It comes preinstalled with the TeX 'medium' scheme + few additional packages.

Select scheme:
===============================================================================
 a [ ] full scheme (everything)
 b [x] medium scheme (small + more packages and languages)
 c [ ] small scheme (basic + xetex, metapost, a few languages)
 d [ ] basic scheme (plain and latex)

See the Dockerfile and .profile files for a full list of installed TeX packages.

In addition, the image provides a headless Java JRE for VeraPDF powered PDF/A validation, Poppler utils for analyzing the generated PDF files (pdfinfo, pdffonts etc.), and Python3 + Pygments for pretty printing source code via the LaTeX minted package.


Basics

Setting up Docker

Setting up Docker requires few preparations.

First, note that Docker uses a client-server architecture. The Docker service needs to be active before any commands will be accepted:

$ systemctl start docker
$ systemctl enable docker

The current user also needs to be a member in the docker group. Invoking Docker actions with sudo docker / as a root user may also work, but both are considered bad practices.

Fetching the image

A prebuilt Docker image is available at UTU GitLab.

Assuming the Docker service has been started, and the current user is a member in the docker group, the build environment can be fetched with the pull command:

$ docker login registry.gitlab.utu.fi
$ docker pull registry.gitlab.utu.fi/tech/soft/thesis/builder

We can list the locally available images with the images command:

$ docker images
REPOSITORY                                      TAG    IMAGE ID            CREATED             SIZE
registry.gitlab.utu.fi/tech/soft/thesis/builder latest 9aaab9b             4 hours ago         3.55GB
...

Compiling the thesis

Assuming the Docker service has been started, and the current user is a member in the docker group, simply launch the LaTeX build script in the project's root directory:

$ docker run -it --mount type=bind,source=$(pwd),target=/thesis registry.gitlab.utu.fi/tech/soft/thesis/builder:latest
root@d662b10721e7:/var/local# cd /thesis
root@d662b10721e7:/tex# latexmk -pdf --shell-escape thesis.tex

If you're using a custom LaTeX image, replace the registry.gitlab.utu.fi/tech/soft/thesis/builder:latest with your tag of choice / image ID.

The document, along with auxiliary build artifacts, will be generated in the project directory (note that the user permissions inside the Docker may differ).

Validating PDF/A conformance

The PDF/A validation tool can be invoked from the command line (in the Docker image / CI task) with the pdfa-validate command:

$ pdfa-validate thesis.pdf

For a conforming document, built in the version=final mode, a successful run of the validation tool (pdfa-validate) will print a single line starting with "PASS". See the PDF/A page for further instructions. A conforming document can be submitted to the UTUGradu system.


Advanced

Building the image

To build the Docker image locally, start the preparations by first cloning the 'thesis' project, then switching to this directory:

$ git clone https://gitlab.utu.fi/tech/soft/thesis/builder
$  cd builder

Assuming the Docker service has been started, and the current user is a member in the docker group, simply launch the build process:

$ docker build . -t custom-builder:latest

The build command will locate the Dockerfile in the current directory and tag the resulting image with custom-builder:latest.

We can list the generated images with the images command:

$ docker images
REPOSITORY           TAG                 IMAGE ID            CREATED             SIZE
custom-builder       latest              3c9e618ad681        4 hours ago         3.55GB

Publishing the image

To publish your Docker image in Docker Hub, switch to the directory where the custom Dockerfile is located, then run build and tag the image with your Docker Hub username as a prefix like so:

$ docker build . -t yourhubusername/yourimage:1.0

Then upload the image:

$ docker login --username=yourhubusername --email=youremail@company.com
WWARNING: login credentials saved in /home/username/.docker/config.json
Login Succeeded

$ docker push yourhubusername/yourimage:1.0

Installing new TeX packages

The provided Docker image uses TeXLive's own package manager (tlmgr) for managing TeX packages. In case the default distribution is missing some important package, one can install additional packages at the end of the Dockerfile
by invoking the following command:

RUN tlmgr install MYPACKAGE1 MYPACKAGE2

The advantage of this approach is that Docker can cache the results of the previous commands, which will speed up the image construction and save bandwidth. See the previous section for instructions on building the image.

See also