Backend Installationsanleitungen

Server

Hinweise zur Test-Umgebung

Aktuell gibt es beim lokalen Testsystem noch ein Problem mit dem logging vom Mailserver. Beim Neustarten der Container-Umgebung funktioniert das Logging nicht. Um das vollständige logging zu erhalten, muss der Container des Mailservers und dessen Volume gelöscht und neu erzeugt werden.

! Bei diesem Prozess gehen etwaige Daten der Conainer verloren und das Volume der Datenbank geht verloren! Zum Zurücksetzen der Container kann

bin/container-reset_all.sh

ausgeführt werden und danach die Umgebung wieder neu gestartet werden.

bin/container-start_all.sh

Erstellen der Keys

Bevor das Projekt genutzt werden kann, muss ein private/public pgp keypaar angelegt werden. Der private Key muss mit einer passphrase versehen sein. Die Namen der Keys und die Passphrase müssen in der compose file hinterlegt werden. Welche Variablen das sind, entnehme dem Environment Abschnitt. Für den Zugriff auf die keys muss im root directory vom projekt ein Ordner namens “keys” angelegt werden und der public und private dort abgespeichert werden. Dieses Keypaar wird zum ausstellen der Server-Zertifikate genutzt. Der erstellte private und public key müssen im Verzeichnis “keys” sein!

Anleitung zum erstellen eines pgp keypaars mit gpg

Ein neues Schlüsselpaar wird (in einem Schritt) mit dem Schalter quick-gen-key erzeugt. Unterschlüssel werden mit dem Schalter quick-add-key an ein bestehendes, eigenes Schlüsselpaar angehängt.

gpg --quick-gen-key <userid> [algo [usage [expire]]]

Es ist üblich, dass die userid eine Emailadresse enthält. Üblich ist es einen Namen anzugeben, die Emailadresse in spitze Klammern zu setzen. Ein Beispiel ist “Lars Fischer lars.fischer@hs-spamschutz-bremerhaven.de”.

Schlüsselexportieren

Public-key

gpg --export --armor <keyid>

Private-key

gpg --export-secret-keys --armor <keyid>

Der Schalter export gibt lediglich die öffentlichen Schlüssel aus dem Schlüsselring aus. Mit dem Schalter –export-secret-keys lassen sich auch private Schlüssel exportieren.

Anleitung von https://informatik.hs-bremerhaven.de/lafischer/tutorials/2023-11-20-gnupg.html zusammenfassen.

Ausführen der Umgebung

Zum reinen Erstellen und Ausführen der Umgebung für die Test- und Produktionsumgebung müssen

  • docker, docker-compose sowie docker-compose-plugin installiert sein
  • der eigene User der Docker Gruppe hinzugefügt sein
    • Alternativ müssen die Skripte, die die docker container steuern, mit sudo gestartet werden.
usermod -aG docker <user>

  • Dann zum erstellen der localen Volumes und Container das Skript project-setup.sh ausgeführen.

    • Der Buildprozess aller Container kann oft mehr als 10 min dauern, also warten
    bin/project-setup

  • Vor dem Ausführen müssen alle benötigten environment variablen im test oder production compose eingetragen sein

  • Im Skript bin/container-start_all.sh die Variable ENVIRONEMNT_TYPE gegebenenfalls anpassen

    • test für locale Testumgebung
    • prod für Production-Umgebung

  • Zuletzt alle container starten mit

    bin/container-start_all.sh

Anhalten der Umgebung

Zum anhalten der Umgebung kann container-stop_all.sh genutzt werden.

bin/container-stop_all.sh

Zurücksetzen der Umgebung

Will man das komplette Projekt zurücksetzen mit Containern und allen Volumes sowie den etwaigen eigenen Änderungen an Config-Dateien im local/-Verzeichnis benutzt man das Skript

bin/project-reset_all.sh

Zum Zurücksetzen der Container ohne auch lokale Änderungen an Config-Dateien im local/-Verzeichnis zu verlieren, benutzt man das Skript

bin/container-reset_all.sh

Dabei gehen allerdings die Daten aus allen Volumes verloren.

Konfigurationen

Die Konfigurationsdateien sind

context/docker-compose-test_env.yml
local/volume_acme-core_config/acme.conf
local/volume_mail-worker-service_config/mail.conf
  • Zu beachten ist: Die Docker Compose hat die höchste Priotität und überschreibt die zugehörigen Enviromentsvariablen der anderen Konfigurationsdateien

Produktivumgebung

Aktivieren der Produktivumgebung

Um die Produktivumgebung zu aktivieren, wird im Skript

bin/container-start_all.sh

die Variable ENVIROMENT_TYPE von test auf prod gesetzt. Dadurch wird die docker-compose-prod_env Datei genutzt.

Konfigurationen

Die Konfigurationsdateien sind

context/docker-compose-prod_env.yml
local/volume_acme-core_config/acme.conf
local/volume_mail-worker-service_config/mail.conf
  • Zu beachten ist: Die Docker Compose hat die höchste Priotität und überschreibt die zugehörigen Enviromentsvariablen der anderen Konfigurationsdateien

Starten

Das Starten, Stoppen und Managen der Container-Umgebung läuft gleich zur Testumgebung ab. Der einzige Unterschied ist das es keinen gesonderten Container für den Mailserver gibt.

Environment Variablen in der Docker-Compose (test & prod)

mail-worker-service

  • MAIL_SERVER_DOMAIN
    • domain oder ip-adresse für den imap/smtp server
  • PRIV_KEY_PATH
    • Path zum private-key innerhalb des mail-worker-service containers
  • PUB_KEY_PATH
    • Path zum public-key innerhalb des mail-worker-service containers
  • PRIV_KEY_PASS
    • Passwort zum entschlüsseln des Private-key
  • MAIL_SERVER
    • IP oder Domain des Mail servers
  • MAIL_USER_NAME
    • Entspricht dem Usernamen im Teil der Email vor dem @-Zeichen
  • MAIL_USER_PASS
    • Enthält ebenfalls das loginpassword für den Mail-account
    • Muss identisch sein zu EMAIL_PASS
  • IMAP_PORT
    • Port des imap-servers auf dem Mailserver
  • SMTP_PORT
    • Port des smtp-servers auf dem Mailserver
  • ACME_CORE_ADDRESS
    • kombination aus ip/domain vom server auf dem das modul acme-core läuft und durch doppelpunkt getrennt der Port auf dem das Modul lauscht
  • MAIL_WORKER_ADDRESS
    • kombination aus ip/domain vom server auf dem das modul mail-worker läuft und durch doppelpunkt getrennt der Port auf dem das Modul lauscht
  • EMAIL_ADDRESS
    • Email-Adresse die als CA genutzt wird
  • EMAIL_PASS
    • Passwort für die Email-adresse die als CA genutzt wird
  • INBOX_NAME
    • Name des Postfaches in dem die eingehenden Nachrichten landen und vom Programm abgerufen werden können
  • INTERVAL
    • Zeit in Millisekunden, wie häufig auf dem Mailserver der Eingang von neuen Mails geprüft wird
  • SECURE_SMTP
    • Setzt, ob bei der SMTP-Verbindung ssl/tls verwendet werden soll, oder nicht
    • Für die Testumgebung muss SECURE_SMTP false sein
    • Für die Produktivumgebung sollte SECURE_SMTP true sein

acme-core

  • DB_ADDRESS (deprecated/FIXME)
    • Muss gesetzt sein, damit skript durchläuft
    • Name vom Datenbank Container
  • DB_CON_STRING
    • String für den Verbindungsaufbau zur Mariadb Datenbank
  • TOKEN_EXPIRATION_SEC
    • Dauer in Sekunden, wie lange auf Abschluss des ACME Prozesses gewartet wird
  • SIGNATURE_EXPIRATION_SEC
    • Gültigkeit in Sekunden von der CA ausgestellten Signaturen
    • Muss mit SIGNATURE_EXPIRATION_DAYS im Verhältnis von sekunden zu tagen übereinstimmen
  • SIGNATURE_EXPIRATION_DAYS
    • Gültigkeit in Tagen von der CA ausgestellten Signaturen
    • Muss mit SIGNATURE_EXPIRATION_SEC im Verhältnis von stunden zu sekunde übereinstimmen
  • ACME_CORE_ADDRESS
    • Kombination aus ip/domain vom Server auf dem das Modul acme-core läuft
    • durch : getrennt der Port auf dem das Modul lauschen soll
  • MAIL_WORKER_ADDRESS
    • lauscht auf http, https in arbeit
    • kombination aus IP/DOMAIN:PORT
  • PRIV_SIGN_KEY_PATH
    • Pfad zum private CA Key zum Keys signieren
  • SECRET_KEY
    • Passwort zum entschlüsseln vom private CA Key

web-api

  • ACME_ADDRESS
    • Kombination aus IP/DOMAIN:PORT der Adresse von acme-core

website/webserver

  • WEB_API
    • Darüber wird der Container der web-api angesprochen
    • Endpunkt der web-api mit protokoll angabe http://[DOMAIN/IP]:PORT
  • DOMAIN_NAME
    • primäre Domain, unter der die Website erreichbar sein soll
  • WEITERE_DOMAIN
    • sekundäre Domain, falls die Website unter einer weiteren Domain erreichbar sein soll
  • REVERSE_PROXY_WEB_API
    • tls encrypted http Weiterleitung an die web-api
      • über die primäre oder sekundäre domain auf port 1194
    • Angabe https://DOMAIN:PORT

Hugo Webserver

Für den Internetauftritt unseres Projektes haben wir uns intern für die Nutzung von Hugo entschieden, auch wenn unsere Webseite nicht statisch ist.

Hugo Installation

Zur Installation von Hugo können die offiziellen Dokumentationen von Hugo genutzt werden:

https://gohugo.io/installation/

Hugo Theme Installation

Die einzelnen Themes für Hugo können hier gefunden werden:

https://themes.gohugo.io/

Jedes Theme hat spezifische Installationsanweisungen. In unserem Projekt haben wir uns für das DPSG-Theme entschieden und die Installationsanweisungen können hier gefunden werden:

https://themes.gohugo.io/themes/hugo-dpsg/

Tipps und Tricks für Hugo

Die darzustellenden Websites müssen als Markdown-Code in dem “content”-Ordner hinterlegt werden. Zusätzlich dazu sollten sie in der hugo.toml im root-Ordner hinterlegt werden für die jeweilige Nutzung bspw. in einer Menüleiste.

Der “public”-Ordner wird komplett von Hugo beim Erstellen der Seite erzeugt und bei Modifikationen auch verwaltet. Dort müssen keinerlei Änderungen durchgeführt werden. Sollte eine Seite nach Modifizierung nicht aktualisieren, hilft es ggf. den “public”-Ordner von Hugo neu erstellen zu lassen mithilfe dieses Befehls:

hugo --cleanDestinationDir

Um html-Code und Javascript mit Hugo effektiv nutzen zu können muss der jeweilige Code unter layouts/shortcodes hinterlegt werden. Diese dort erstellten HTML-Snippets können dann bei den Markdown-Webseiten mit folgender Formatierung ( ohne Leerzeichen nach “{”, bzw. ohne Leerzeichen vor “}” ) eingefügt werden:

{ { < Shortcode-Name > } }

Gestartet werden kann der Hugo Server mit dem einfachen CLI-Befehl:

hugo server

Oder auch ohne Fast Render Mode:

hugo server --disableFastRender