Docker

Warning

The BFH LaTeX Docker image is available exclusively to BFH members.

Warning

We recommend choosing a specific tag at all times instead of latest. However, you will see latest in the documentation, replace it with any version tag of the BFH CI releases - starting from 1.5.2.

Configuration

To access the Docker image, you will need to log in to our registry first. Use a terminal, PowerShell, or another command-line tool (it does not work with Docker Desktop).

$ mkdir -p ~/.docker && cat > ~/.docker/config.json <<EOF
{
  "auths": {},
  "credsStore": "desktop",
  "experimental": "enabled"
}
EOF

Note

"credsStore": "desktop" → tells Docker to use the system credential store (you can change it to "osxkeychain", "pass", "secretservice", or "wincred" depending on your OS).

Next, create an access token that you use instead of your password. The access token must have read capabilities on the registry. A working example of token properties is the following.

Note

read_repository, read_virtual_registry, read_registry, read_api, read_user

Further reading:

Log in with your BFH credentials (abbreviation, e.g. user6) and a token instead of the password.

$ docker login registry.gitlab.ti.bfh.ch
Username: <ENTER i.e. user6>
Password: <ENTER token of user6>

Check whether the login was successful.

$ docker login --get-login registry.gitlab.ti.bfh.ch

The expected output will be your username in the example above, i.e., user6.

Note

The above command might require admin privileges. But you could also add your user account to the docker group with e.g.:

# usermod -aG docker <USER>

Introduction

For a general usage overview of Docker, please read their official documentation

In general, we provide two slightly different images:

1. Plain BFH LaTeX

This image contains all the required packages to build our templates, such as Inkscape, latexmk, make, …, it does not include the templates or examples.

It can be used to:

  • Run pipelines building a LaTeX document in GitLab

  • Build documents manually (i.e. without VSCode integration) on a local system

  • Testing / Trying

  • …

2. VSCode Compatible

Note

It is the recommended and most convenient way for local development with Docker. Please read here for more information about the usage.

The image is designed to fit the requirements for the VSCode Remote Container Extension. It contains the same packages as the Plain BFH LaTeX image, with some additions:

  • Extensions and Configuration for LaTeX editing in VSCode

  • Templates and examples from the BFH CI

It can be used mainly for VSCode. Clearly, you are also free to use it the same way as the Plain BFH LaTeX image.

Using the VSCode Image

Please continue here.

Using the Plain Image

As stated earlier, the most efficient way is to use the VSCode image together with VSCode. However, you should edit on the command line.

Note

Some features, like live updates (-pvc for latexmk), will not function out of the box. For example, with -pvc, you must also use -view=none when inside the container.

Develop inside the image

To develop directly inside the image, it needs to be extended first. So extend the image as described here and install a text editor of your choice. Then run the image like this:

$ docker run -it --rm \
             -v <ABSOLUTE_PATH_TO_LATEX_PROJECT>:/home/bfhlatex/project \
             -w /home/bfhlatex/project \
             bfh-latex-extended:latest

It will create an interactive shell in the container, where you can start editing with the editor you previously installed. Then run latexmk for example.

Explanation:

  • -it: launch an interactive shell

  • --rm: remove the container (not the image) as soon as you stop it (e.g. with Ctrl+c)

  • -v: mount your tex project directory into the container at /home/bfhlatex/project

  • -w: set the working directory into the tex project dir (shell will be launched there)

Warning

Any changes that are made to files which are not mounted from the host into the container (or vice-versa) will be gone once the container exits.

Develop on the host and build with the container

Clearly, you can also edit all the files on your system and use the container only to build. To do so, run the following command once you want to build the documentation:

$ docker run -it --rm \
             -v <ABSOLUTE_PATH_TO_LATEX_PROJECT>:/home/bfhlatex/project \
             -w /home/bfhlatex/project \
             registry.gitlab.ti.bfh.ch/bfh-latex/registry/bfh-ci:latest \
             latexmk

Use docker-compose

You can translate the above commands directly into a compose file to circumvent having to execute the commands for each build. However, this is not part of this documentation. If you would like to do so, please continue reading here.

A simple working example is the following (placed in the LaTeX project root directory):

docker-compose.yaml

version: "3.7"
services:
  latex-bfh:
    image: registry.gitlab.ti.bfh.ch/bfh-latex/registry/bfh-ci:latest
    volumes:
      - ${PWD}:/home/bfhlatex/project
    working_dir: /home/bfhlatex/project
    command: "latexmk -pvc -view=none"

It will trigger on changes in the source files and continuously build until aborted.

To start, run e.g.:

$ docker-compose up

Extending an Image

You can extend our images locally if you need additional packages to build your TeX document. To do so, create a new Dockerfile (example):

Note

It is not needed to create an own image when using VSCode, please see here for more information.

Dockerfile

FROM registry.gitlab.ti.bfh.ch/bfh-latex/registry/bfh-ci:latest

USER root

RUN apt install -y vim && \
    tlmgr update --self && \
    tlmgr install siunit

USER bfhlatex

Build the image with e.g. the following command:

$ docker build . -t bfh-latex-extended:latest