Docker

Note

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

Note

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 2.2.3.

Prerequisites

To use the Docker image, you must have Docker installed (install Docker first if you haven’t yet) and be logged in to our registry on GitLab, as described below.

Logging in to the Docker registry

Warning

To be able to use our Docker images, you must be logged-in to our registry on GitLab, else pulling images will fail.

Warning

For the login to succeed, you need a personal access token from GitLab. Plain username and password will not work!

Follow the steps below to login with docker to our registry:

  1. Head to your profile page on GitLab

  2. Click Add new token

  3. Give it a meaningful name (e.g. bfh-latex-pull-token)

  4. Select the maximum expiration possible

  5. Select read_registry scope only

  6. Click Generate token

  7. Copy the token displayed at the top of the page

  8. Open a terminal and login to the registry

    This must be done on a terminal (PowerShell, bash, …); the commands stay the same regardless of which one you use.

    $ docker login registry.gitlab.ti.bfh.ch -u <YOUR_GITLAB_USERNAME>
Password:

    When asked, paste the copied token from before.

  9. Check if the login suceeeded by pulling one of our images

    $ docker pull registry.gitlab.ti.bfh.ch/bfh-latex/registry/bfh-ci:latest
...

    Note

    Should the pull fail in the future with access denied, it’s likely your token has expired. Repeat the token creation and login again.

Further reading:

Our Images

We provide two main images for slightly different use-cases

VS Code BFH LaTeX

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 be used with the VS Code Dev Containers extension. It contains the same packages as the Plain BFH LaTeX image, with some additions:

  • Extensions and Configuration for LaTeX editing in VS Code

  • Templates and examples from the BFH CI

Using the VS Code Image

Important

Besides Docker, you need VS Code with the Dev Containers extension installed.

Continue with VS Code →

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 VS Code integration) on a local system

  • Testing / Trying

  • …

Using the Plain Image

This plain image has no editor integration, so you edit your LaTeX files on the command line (or in an editor on the host, see below). If you want editor integration instead, use the VS Code BFH LaTeX image.

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.

Example Usages

Develop directly in the image

To develop directly inside the image via docker, it needs to be extended with a text editor first (for example vim). So extend the image as described in Extending an Image 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) are ephemeral and will be lost once the container exits.

Develop on the host and build with the container

You can also use the Docker image as a plain builder for the LaTeX files you edit on the developer machine. To do so, run the following command once you want to build the documentation (assuming latexmk is configured accordingly in your project):

$ 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 the official compose docs.

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"

Explanation:

  • Most of the entries are direct translations from the commands above (such as volumes, working_dir, …)

  • The latexmk argument -pvc means “preview continuously”, meaning the build process will automatically trigger whenever you change your files in an editor, resulting in live previews of your changes. This can also be used with docker run above.

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 VS Code, 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
...