server-test-local.md

+# Lokales Testen eines Python-Serverprozesses
+
+Die im Labor wichtigen Serverprozesse wie z.B. `bur` oder `cal` laufen auf einem zentralen Rechner und sind somit leicht allgemein erreichbar. Für Testzwecke (z.B. Anpassungen von Kalibrierschein-Templates) ist es dagegen günstig, den betreffenden Serverprozess lokal zu betreiben, um damit einfacher das Ergebnis beurteilen zu können und auch um ggf. aussagekräftige Fehlermeldungen zu erhalten. Im Folgenden wird am Beispiel des `bur`-Servers gezeigt, wie man vorgehen muss.
+
+Es sei angemerkt, dass alles Folgende nicht oder nur mit immensem Aufwand unter dem Beriebssystem »Windows« erledigt werden kann. »Linux« ist daher zwingend nötig.
+
+## Clonen des Git-Repositoriums
+
+```
+cd Arbeitsverzeichnis
+git clone https://gitlab1.ptb.de/vaclab/bur.git
+```
+
+Der Clone-Prozess erfordert noch keine Eingabe von Nutzernamen und Passwort, da das Repositoriums den Status »öffentlich« hat.
+
+## Nutzernamen und Passwort permanent bekanntmachen
+
+Um das Git-Repositorium effektiv zu nutzen, empfiehlt es sich, Nutzernamen und Passwort der Git-Konfiguration hinzuzufügen, um nicht jedes Mal z.B. bei »`git push`« Eingaben ausführen zu müssen. Das kann folgendermaßen geschehen. 
+
+```
+cd bur/.git
+```
+
+Die dort befindliche Datei `config` enthält die Zeile
+
+```
+url = https://gitlab1.ptb.de/vaclab/bur.git
+```
+
+Sie kennzeichnet, wie auf das serverseitige Git-Repositorium zugegriffen wird. Mit einem Texteditor (z.B. »Visual Studio Code«, »VSCodium«, »Geany«, ...) kann man die URL durch die Angabe von Nutzernamen und Passwort erweitern, um sich ggf. beim Server zu autorisieren. Die zu ändernde URL bekommt die folgende Form
+
+```
+https://UUUU:PPP@gitlab1.ptb.de/vaclab/bur.git
+```
+
+* `UUUU` = Nutzername
+* `PPPP` = Passwort
+  
+Beachtet werden muss dabei, dass die Zeichen »`@`« und »`:`«, sofern sie im Nutzername oder im Passwort enthalten sind, durch ihr sogenanntes URL-Encoding ersetzt werden müssen, da sie ja bereits als Trennzeichen in der URL-Struktur dienen. Der Nutzername ist beim PTB-GitLab-Server grundsätzlich eine gültige E-Mail-Adresse, weshalb das darin enthaltene `@`-Zeichen in jedem Fall ersetzt werden muss. Es gilt:
+
+| Zeichen | URL-Encoding |
+|---------|--------------|
+|  `@`    |   `%40`      |
+|  `:`    |   `%3A`      |
+
+Beispiel einer korrekten URL mit fiktivem Passwort:
+
+* Nutzername: `Ute.Becker@ptb.de`
+* Passwort: `James:Bond`
+
+```
+https://Ute.Becker%40ptb.de:James%3ABond@gitlab1.ptb.de/vaclab/bur.git
+```
+
+Nachdem die URL in der Datei `config` in dieser Weise geändert wurde, entfällt künftig die Eingabe von Nutzernamen und Passwort.
+
+## Installieren und Starten des lokalen Python-Serverprozesses
+
+Wechseln zurück ins Git-Arbeitsverzeichnis:
+
+```
+cd ..
+```
+
+### Installation der benötigten Python-Bibliotheken in einer virtuellen Python-Umgebung
+
+```
+python3 -m venv ./  # Anlegen der virtuellen Python-Umgebung
+source bin/activate # Aktivieren der virtuellen Python-Umgebung
+pip3 install --upgrade pip
+pip3 install -e .   # Python-Bibliotheken installieren
+```
+
+### Starten des Python-Serverprozesses
+
+```
+./bur
+```
+
+Als Folge kann nun über den eigenen Rechner (`localhost`) auf die in der Beschreibung (siehe Git-Repositorium) genannten Schnittstellen zugegriffen werden. Führt man Änderungen an den zum Serverprozess gehörenden Dateien aus, startet der Serverprozess automatisch neu, womit die Änderungen sofort wirksam sind.
+
+## Zugriff auf den lokalen Serverprozess
+
+Dazu startet man ein neues Terminal. Darin kann mit Hilfe des Programms `curl` auf die lokalen URLs des Serverprozesses zugerfiffen werden. Als Beispiel soll hier die Erzeugung des LaTeX-Quelltextes für ein Angebotsschreiben dienen. An die URL der Schnittstelle »offer« muss die ID des Planungsdokuments in der Datenbank angehangen werden (hier `pla-ptb_ag_7.54-2023-001`).
+
+```
+curl http://localhost:5000/pla/offer/pla-ptb_ag_7.54-2023-001
+```
+
+Sollte die Kommunikation mit dem Serverprozess zu einem Python-Fehler führen, kann man dies in dem Terminal, in welchem der Serverprozess gestartet wurde, beobachten und seine Schlüsse ziehen. Interessiert man sich dagegen für inhaltliche Fehler des LaTeX-Codes, empfiehlt es sich, die Ausgabe des curl-Aufrufes in eine Datei umzuleiten, die dann z.B. mit `lualatex` zu einem PDF-Dokument kompiliert werden kann:
+
+```
+curl http://localhost:5000/pla/offer/pla-ptb_ag_7.54-2023-001 > zz.tex
+lualatex zz.tex
+```
+
+Die gleichen Vorgänge, die hier mit Hilfe von `curl` simuliert wurden, werden in ähnlicher Weise durch die Web-Applikation `Sofa` ausgelöst, können dort aber nur bedingt analysiert werden. 
+
+## Beenden des lokalen Serverprozesses
+
+Abbruch mit `Strg C` und danach Deaktivieren der virtuellen Python-Umgebung:
+
+```
+deactivate
+```
+
+---
+`RN 01/2024`
+
+
+
+
+
+
+
+
+
+
+
+
+
+