Docker

Warning

The BFH LaTeX Docker image is available for BFH members only.

Warning

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

Configuration

To have access to the docker image you will have to login to our registry first. Use a terminal, Powershell or some other command line tool (it does not work with Docker desktop).

Login with your BFH Credentials (abbreviation, e.g. user6)

$ docker login registry.gitlab.ti.bfh.ch
Username:

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 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. withouth VSCode integration) on a local system

  • Testing / Trying

  • …

2. VSCode Compatible

Note

This is the recommended and most convenient way for local development with Docker, please read here for more information about the usage.

This image is designed to be fitting 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 might want to edit on the command line.

Note

Some features like live updates (-pvc for latexmk) will not be functioning out of the box. E.g. for -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 texteditor 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

This will create an interactive shell into the container in which you can start editing with the editor you installed previously. 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 lanched 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 to build only. 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"

This will watch for changes in the source files and continously 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