==============================
Experiment 3: [Gitlab CI/CD]
==============================

Datum: [2.05.2024]
Thema: [Gitlab CI/CD]

Einleitung
----------
Gitlab bietet die möglichekit eine CI/CD (Continuos Integration / Continuos deployment) Pipline zu erstellen. 
In diesem Experiment wird eine CI/CD Pipline erstellt, welche bei jedem push auf den main branch die Sphinx Dokumentation erstellt und auf Gitlab Pages veröffentlicht.


Motivation
----------

Für jedes Projekt wird eine neue Seite in der Sphinx Dokumentation erstellt, welche erneut gebaut und veröffentlicht werden muss. 
Um die repitive Arebeit zu vermeiden erstellen wir dafür eine CI/CD Pipline.

Aufgabenstellung
----------------
Um die CI/CD Pipline zu erstellen müssen folgende Schritte durchgeführt werden:

#. Docker auf einem Server installieren
#. Docker Container mit Gitlab Runner erstellen
#. Python Umgebung auf dem Docker Container installieren
#. SSH Key auf dem Docker Container installieren
#. Gitlab Runner in Gitlab registrieren
#. Gitlab CI/CD Pipline erstellen

Durchführung
------------
1. Docker auf einem Server installieren
    Bei dem Server handelt es sich um einen Windows 11 PC. Auf Windows 11 ist es möglich Docker Desktop unter folgendem Link zu installieren: https://docs.docker.com/desktop/install/windows-install/

2. Docker Container mit Gitlab Runner erstellen
    Um einen Docker Container mit Gitlab Runner zu erstellen, muss folgender Befehl ausgeführt werden:
    
    .. code-block:: bash

      $ docker run -d --name gitlab-runner --restart always \
      $ -v /srv/gitlab-runner/config:/etc/gitlab-runner \
      $ -v /var/run/docker.sock:/var/run/docker.sock \
      $ gitlab/gitlab-runner:latest

    
    Dieser Befehl erstellt einen Docker Container mit dem Namen gitlab-runner, welcher bei jedem Neustart des Servers automatisch startet.

3. Python Umgebung auf dem Docker Container installieren
    Um die Sphinx Dokumentation zu erstellen, muss Python auf dem Docker Container installiert werden.
    Über Docker Desktop is es einfach möglich auf die Konsole des Containers zuzugreifen. 
    Der Container läuft auf einer Ubuntu Umgebung, daher kann Python mit folgendem Befehl installiert werden:
    
    .. code-block:: bash

      $ apt install python3 -y
      $ apt install python3-pip -y
    
    Mit diesen Befehlen wird Python und pip installiert. Alle weiteren benötigten Pakete werden direkt in der CI/CD Pipline installiert.

4. SSH Key auf dem Docker Container installieren
    Um später die sphinx doku aoutmatisch auf das rz Laufwer zu kopieren muss ein SSH Key auf dem Docker Container installiert werden.
    
    .. code-block:: bash

      $ ssh-keygen -t rsa -b 4096 -C "schmigo"
      $ ssh-copy-id -i ~/.ssh/id_rsa.pub schmigo@login.rz.hs-augsburg.de

    Nach dem ausfüheren dieser Befehle ist es möglich sich ohne Passwort auf das rz Laufwerk zu verbinden.


5. Gitlab Runner in Gitlab registrieren
    Um den Gitlab Runner in Gitlab zu registrieren muss zunächst im Gitlab Projekt unter CI/CD Settings -> New Runner ein neuer Runner erstellt werden.
    .. image:: img/create_cicd_runnter.png
        :scale: 50 %
    
    Nachdem der Runner erstellt wurde, wird eine Token angezeigt, welcher benötigt wird um den Runner im Container zu registrieren.
    Der Runner kann mit folgendem Befehl registriert werden:

    .. code-block:: bash   

      $ gitlab-runner register
    
    Nach dem ausführen des Befehls wird nach der Gitlab URL ind em fall https://gitlab.informatik.hs-augsburg.de/ und dem Token welcher im Schritt davor erstellt wurde, gefragt.

    Wenn alles richtig gelaufen ist sollte der Runner im Gitlab Projekt unter CI/CD Settings -> Runners angezeigt werden.

6. Gitlab CI/CD Pipline erstellen
    Um die CI/CD Pipline zu erstellen muss im Projekt ein .gitlab-ci.yml File erstellt werden.
    In diesem File wird definiert was bei jedem push auf den main branch passieren soll.
    Hier ein Beispiel für ein .gitlab-ci.yml File:
    
    .. code-block:: yaml
      
      image: python:3.7-alpine

      test:
        stage: test
        script:
        - pip install -U sphinx
        - sphinx-build -b html docs/source public
        only:
        - branches
        except:
        - main

      deploy:
        stage: deploy
        script:
        - pip install -U sphinx
        - sphinx-build -b html docs/source public
        - ssh -4 -o StrictHostKeyChecking=no schmigo@login.rz.hs-augsburg.de "rm -rf /www/schmigo/*"
        - scp -r public/* schmigo@login.rz.hs-augsburg.de:/www/schmigo/
        artifacts:
          paths:
          - public
        only:
        - main
    
    In diesem File wird definiert, dass bei jedem push auf den main branch die Sphinx Dokumentation erstellt wird und auf Gitlab Pages veröffentlicht wird.

Probleme
--------
Das größte problem ist, dass der Gitlab Server der Hochschule nur durch eine VPN Verbindung erreichbar ist.
Daher muss der Server auf dem der Gitlab Runner läuft ständing mit dem VPN verbunden sein. 
Die Hochschule stellt jedem Studenten eine VPN Zugang zur Verfügung, jedoch kann immer nur ein Gerät gleichzeitig verbunden sein.
Das bedeutet, dass wenn dieser Student den VPN Zugang nutzt, der Gitlab Runner nicht mehr erreichbar ist.

Zukünftige Arbeiten
-------------------
In zukünftigen Arbeiten sollte eine Lösung für das Problem mit dem VPN Zugang gefunden werden. 
Auserdem ist akutell sehr viel manuelle Arbeit notwendig um den Gitlab Runner zu erstellen und zu konfigurieren.
In zukunft sollte für das einrichten des Runners beispielsweise ein fertiges Docker compose File zur Verfügung gestellt werden, um die manuelle einrichtung von Python und pip zu vermeiden.