LaTeX Container

Getting Started Dockerfile

user@system:~$ mkdir latexContainer && cd latexContainer
user@system:~/latexContainer$ vim Dockerfile

Dockerfile

FROM debian:stable-20190708-slim                                                                                                                            
MAINTAINER Matthias WAELTI <wlm2@bfh.ch>

RUN echo "Hello Docker"

Wir verwenden ein “base image” basierend auf debian stable vom 07.08.2019. “slim” verweisst auf die verwendeten Tools innerhalb der Distribution, wobei auf grafische Oberflächen und Benutzerhandbücher verzichtet wird.

user@system:~/latexContainer$ docker build .

Sending build context to Docker daemon  2.048kB
Step 1/3 : FROM debian:stable-20190708-slim
stable-20190708-slim: Pulling from library/debian
161134cb67dc: Pull complete 
Digest: sha256:fb24d5c869a1c878ed22840096d50f7d5459370f64a21191042e2b138244e8ae
Status: Downloaded newer image for debian:stable-20190708-slim
 ---> a4eb8e3265f8
Step 2/3 : MAINTAINER Matthias WAELTI <wlm2@bfh.ch>
 ---> Running in 37ec39a04673
Removing intermediate container 37ec39a04673
 ---> 3b2d651f9711
Step 3/3 : RUN echo "Hello Docker"
 ---> Running in 3a47e7213092
Hello Docker
Removing intermediate container 3a47e7213092
 ---> 6e64bd0ec3e4
Successfully built 6e64bd0ec3e4

Mit dem Kommando docker build . wird auf der Basis eines Dockerfiles welches sich im “present working directory” befindet ein Docker-Image erstellt. Da das Base-Image von debian nicht vorhanden ist, wird es nachgeladen und ist von nun an lokal verfügbar. Während des dritten Build-Steps sehen wir die Ausgabe “Hello Docker”.

user@system:~/latexContainer$ docker image ls
REPOSITORY          TAG                    IMAGE ID            CREATED             SIZE
<none>              <none>                 6e64bd0ec3e4        2 minutes ago       69.2MB
debian              stable-20190708-slim   a4eb8e3265f8        2 weeks ago         69.2MB

Das Kommando docker image ls listet alle vorhandenen Docker-Images auf. Eines der Images ist das debian Base-Image, das Andere ist das eben erstellte Image, welches noch keinen Namen trägt.

~:
$ docker build -t="cauchy/latex:1.0.0" .
Sending build context to Docker daemon  2.048kB
Step 1/3 : FROM debian:stable-20190708-slim
 ---> a4eb8e3265f8
Step 2/3 : MAINTAINER Matthias WAELTI <wlm2@bfh.ch>
 ---> Using cache
 ---> 3b2d651f9711
Step 3/3 : RUN echo "Hello Docker"
 ---> Using cache
 ---> 6e64bd0ec3e4
Successfully built 6e64bd0ec3e4
Successfully tagged cauchy/latex:1.0.0

Nun wird das selbe Image erneut erstellt, dieses Mal jedoch mit einem Namen und einer Versionsnummer.

~:$ docker image ls --all
REPOSITORY          TAG                    IMAGE ID            CREATED             SIZE
cauchy/latex        1.0.0                  6e64bd0ec3e4        About an hour ago   69.2MB
<none>              <none>                 3b2d651f9711        About an hour ago   69.2MB
debian              stable-20190708-slim   a4eb8e3265f8        2 weeks ago         69.2MB

Werden nun alle Images gelistet, mit der Option --all, so sehen wir nicht nur das Base-Image sondern auch das erste Image ohne Namen und das neue Image mit Namen und Versionsnummer.

LaTeX Dokerfile

Dockerfile>

FROM debian:stable-20190708-slim                                                                                                                            
MAINTAINER Matthias WAELTI <wlm2@bfh.ch>

ENV REFRESHED_AT 24.07.2019

RUN apt update && apt upgrade -y

RUN apt install -y make

RUN apt install -y doxygen \
doxygen-latex

RUN apt install -y texlive-base

Mit dem Befehl ENV erstellen wir eine Environment-Variable welche zur Versionisierung dient. Anschliessend werden die Paketquellen aktuallisiert und ggf. Pakete erneuert. Für den Anfang werden die Pakete

  • make

  • doxygen

  • doxygen-latex

  • texlive-base

installiert.

Um das Verhalten von Doxygen und LaTex in einem Container zu untersuchen erstellen wir ein minimales C File welches wir dokumentieren wollen·

main.c

#include <stdio.h>    

/*! \file */                                                                                                                                      
  
/**
 * @brief Simple "Hello World" function.
 *
 * This function will print a "Hello World" message to the standard output
 * stream.
 *
 * @param No parameter.
 * @return No return.
 */
void helloWorld(void)
{
    puts("Hello World");
}

int main(void)
{
    helloWorld();
}

Weiter wird ein minimales Config-File für doxygen benötig. Dafür kann mit dem Befehl

~:
$ doxygen -g <FILE_NAME>

eine standard Konfiguartionsdatei erstellt werden. Wir verwenden den Namen config.doxy.

Nun werden einige minimale Veränderungen am config.doxy file vorgenommen. Die hier aufgelisteten Zeilen befinden sich nicht direkt nacheinander, sie sind aber bereits alle vorhanden und können gesucht werden.

PROJECT_NAME           = "Hello World"   
OUTPUT_DIRECTORY       = _build

Nun können wir mit folgendem Befhel Doxygen und LaTex zuerst lokal testen:

doxygen config.doxy && make -C _build/latex/ && xdg-open _build/latex/refman.pdf

Nun wollen wir zuerst Doxygen alleine im Container ausführen, dazu setzten wir folgenden Befehl ab:

docker run --rm -v $(pwd):/usr/src -w /usr/src cauchy/latex:1.0.0 doxygen config.doxy

Befehle:

  • run Startet einen Container

  • --rm Entfernt den Container nach Beendigung des Prozesses.

  • -v $(pwd):/usr/src Mountet den lokalen Ordner an den spezifizierten Pfad. -v <LOKALER_PFAD>:<CONTAINER_PFAD>

  • -w /usr/src Legt das “Working-Direktory” im Container fest.

  • cauchy/latex:1.0.0 Spezifiziert das Image auf dessen Grundlage der Container erstellt wird.

  • doxygen config.doxy Startet Doxygen mit der angegebenen Konfigurationsdatei.

Um die ganze Toolchain zu testen werden wir den Container nun mit der Option ‘’%%-it%%’’ im interaktiven Modus starten.

~:
$ docker run -it -v $(pwd):/usr/src cauchy/latex:1.0.0

So können wir die Befehle manuell absetzten.

root@ed6667ebe9fd:/# cd /usr/src/
root@ed6667ebe9fd:/usr/src# doxygen config.doxy 
root@ed6667ebe9fd:/usr/src# make -C _build/latex/
root@ed6667ebe9fd:/usr/src# exit                   
exit

Mit dem Befehl exit wird der Container verlassen.

Gitlab Registration

Nun wollen wir unseren Container auf GitLab registrieren. Dazu erstellen wir auf Gitlab eine Gruppe mit einem Projekt. Für das Projekt verwenden wir unser main.c File welches wir bisher genutzt haben.

Die Gruppe nennen wir “Docker Example” und das Projekt “myFirstBuildPipeline”. Im Projekt müssen nun unter Settings/General die Optionen “Pipelines” und “Container registry” eingeschaltet werden. Dadurch erscheint im linken Reiter eine neue Option “Container registry”. Dort können wir die erlaubten Nomenklaturen für die Container einsehen.

Da wir die bisher erstellten Images nicht mehr alle benötigen, entfernen wir nun alle Images, Container und Volumes mit dem Befehl:

docker system prune -a

Als nächstes bilden wir das Image neu “from scratch” mit dem richtigen Namen und Tag und “pushen” diesen zum Projekt. Doch zuerst müssen wir und mit docker bei GitLab anmelden:

docker login registry.gitlab.ti.bfh.ch

Anschliessend bilden wir das Image neu und pushen es.

docker build -t registry.gitlab.ti.bfh.ch/docker-example/myfirstbuildpipeline/latex:1.0.0 .
docker push registry.gitlab.ti.bfh.ch/docker-example/myfirstbuildpipeline/latex:1.0.0

Nach dem Neuladen der Seite sollte das registrierte Image auf GitLab erscheinen.

.gitlab-ci.yml File

Wir erstellen ein neues File mit dem Namen .gitlab-ci.yml und dem folgenden Inhalt:

.gitlab-ci.yml

#image: registry.gitlab.ti.bfh.ch/docker-example/myfirstbuildpipeline/latex:1.0.0

stages:
    - api-doc

make-doc:
    stage: api-doc
    tags:
        - ubuntu
        - center

    image: registry.gitlab.ti.bfh.ch/docker-example/myfirstbuildpipeline/latex

    script:
        - ln -fs /usr/share/zoneinfo/right/Europe/Zurich /etc/localtime
        - doxygen config.doxy
        - make -C _build/latex

    artifacts:
        name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME"
        when: on_success
        paths:
            - _build/latex/refman.pdf

Anschliessend kann das git Repositori bestehend aus

  • main.c

  • config.doxy

  • .gitlab-ci.yml

gepusht werden. Nun sollte die Pipeline fehlerfrei durchlaufen und am Ende die Artefakte zur Verfügung stehen.

UNSORTED TODO

~:
$ docker container ls

Listet alle vorhandenen Container.

~:
$ docker rm <CONTAINER_ID>

Entfernt einenen container.

~:
$ docker rm $(docker ps -a -q)

Entfernt alle bestehenden container.

~:
$ docker search <TAG>

Sucht nach einem docker Image mit dem spezifizierten TAG.

~:
$ docker search --filter "is-official=true" <TAG>

Sucht nach einem ofiziellen Image mit dem spezifizierten TAG.

A pre-built container can be found here: [[https://gitlab.ti.bfh.ch/latex-utils/texlive]]

docker pull registry.gitlab.ti.bfh.ch/latex-utils/texlive:latest

This docker container can also be used for CI/CD purposes within GitLab. An example ‘’.gitlab-ci.yml’’ could look as follows:

.gitlab-ci.yml

image: registry.gitlab.ti.bfh.ch/latex-utils/texlive:latest

variables:
  GIT_SUBMODULE_STRATEGY: noraml

build:
  script:
    - MAINFILE=main.tex make document
  artifacts:
    paths:
      - "_output/*.pdf"