Docker

Docker Introduction

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

Install

Docker can package an application and its dependencies in an encapsulated environment, also known as a container, that can run on any GNU/Linux, Windows, or macOS system. To install Docker on your host, follow the OS-dependent instructions on the official website. The link below will take you there.

Docker manual

Post-Installation Steps

Follow the BFH LaTeX on Docker documentation to get Docker set up to use our private images.

Our Images

We provide two main images for slightly different use-cases

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.

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 fit the requirements for the VS Code Remote Container 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

Please continue here.

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