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.