Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
doku:technische_dokumentation [2022/10/05 22:32] – [Pipeline] frederike_lmzdoku:technische_dokumentation [2022/10/07 11:40] (aktuell) – [Dokumentation Tests] frederike_lmz
Zeile 160: Zeile 160:
 ===== Dokumentation Website ===== ===== Dokumentation Website =====
  
-Das Frontend von Blockalot ist der Teil der Anwendung, den die Endnutzer bedienen, um ihre Klassenzimmer zu verwalten.+Das Frontend von BLOCKALOT ist der Teil der Anwendung, den die Endnutzer bedienen, um ihre Lernräume zu verwalten.
  
 ==== Design ==== ==== Design ====
  
-Das Design der Website orientiert sich am Corporate Design des LMZ: Die Farben, insbesondere Orange und Olivgrün, der Homepage des LMZ wurden übernommen. Auch das Logo sowie einige Grafiken wurden übernommen beziehungsweise abgewandelt. Für einige Elemente, zum Beispiel die "Karten" der Klassenzimmer auf dem Dashboard, wurde //Neomorphismus//  verwendet. Dieser sorgt zwar für ein modernes Aussehen, dessen Tauglichkeit, insbesondere im Bezug auf Kontrast, sollte weiter überprüft werden.+Das Design der Website orientiert sich am Corporate Design des LMZ: Die Farben, insbesondere Orange und Olivgrün, der Homepage des LMZ wurden übernommen. Auch das Logo sowie einige Grafiken wurden übernommen beziehungsweise abgewandelt. Für einige Elemente, zum Beispiel die "Karten" der Lernräume auf dem Dashboard, wurde //Neomorphismus//  verwendet. Dieser sorgt zwar für ein modernes Aussehen, dessen Tauglichkeit, insbesondere im Bezug auf Kontrast, sollte weiter überprüft werden.
  
 Ein Mockup für die Website wurde mit //Figma//  erstellt. Über [[https://www.figma.com/file/hDVSUEyJKd6Oij7IlE01A1/Mockup?node-id=0%3A1|diesen Link]] kann es eingesehen werden. Falls Änderungen vorgenommen werden müssen, wenden Sie sich bitte an //rech1033@hs-karlsruhe.de//, um Zugriff zu erhalten. Ein Mockup für die Website wurde mit //Figma//  erstellt. Über [[https://www.figma.com/file/hDVSUEyJKd6Oij7IlE01A1/Mockup?node-id=0%3A1|diesen Link]] kann es eingesehen werden. Falls Änderungen vorgenommen werden müssen, wenden Sie sich bitte an //rech1033@hs-karlsruhe.de//, um Zugriff zu erhalten.
Zeile 180: Zeile 180:
 ==== Aufbau ==== ==== Aufbau ====
  
-Die Root-Datei ist //src/App.vue.//  Hier werden die //Navbar//, der //Footer//  und die aktuelle //View//  eingebunden. Die aktuelle View wird über //Vue-Router//  bestimmt, die entsprechende Datei ist //src/router/index.js//. Die Views liegen unter //src/views//  und entsprechen den unterschiedlichen Seiten der Anwendung (Home, Dashboard, FAQ, Klassenzimmer, Impressum und Datenschutz).+Die Root-Datei ist //src/App.vue.//  Hier werden die //Navbar//, der //Footer//  und die aktuelle //View//  eingebunden. Die aktuelle View wird über //Vue-Router//  bestimmt, die entsprechende Datei ist //src/router/index.js//. Die Views liegen unter //src/views//  und entsprechen den unterschiedlichen Seiten der Anwendung (Home, Dashboard, FAQ, Lernräume, Impressum und Datenschutz).
  
 Die Views binden unterschiedliche Komponenten ein, welche unter //src/components//  gespeichert werden. Einige dieser Komponenten, zum Beispiel der Button, können innerhalb des gesamten Frontends wiederverwendet werden. Mit //Vuese//  können mehr Informationen über die einzelnen Komponenten generiert werden. //Vuese//  erstellt automatisch eine Dokumentation der Komponenten. Die generierten Dateien sind in //Markdown//  geschrieben und liegen unter //website/components//. Es kann eine Website lokal gehostet werden, die alle //Markdown//-Dateien der Komponenten-Dokumentation aufbereitet darstellt. Hierfür muss global //Vuese//  installiert und anschließend //vuese serve –open//  ausgeführt werden (siehe [[https://vuese.org/cli|Vuese-Dokumentation]]). Die Views binden unterschiedliche Komponenten ein, welche unter //src/components//  gespeichert werden. Einige dieser Komponenten, zum Beispiel der Button, können innerhalb des gesamten Frontends wiederverwendet werden. Mit //Vuese//  können mehr Informationen über die einzelnen Komponenten generiert werden. //Vuese//  erstellt automatisch eine Dokumentation der Komponenten. Die generierten Dateien sind in //Markdown//  geschrieben und liegen unter //website/components//. Es kann eine Website lokal gehostet werden, die alle //Markdown//-Dateien der Komponenten-Dokumentation aufbereitet darstellt. Hierfür muss global //Vuese//  installiert und anschließend //vuese serve –open//  ausgeführt werden (siehe [[https://vuese.org/cli|Vuese-Dokumentation]]).
Zeile 190: Zeile 190:
 ===== Dokumentation Keycloak ===== ===== Dokumentation Keycloak =====
  
-Der Keycloak-Server wird zur //Benutzerverwaltung//  für die User der Webseite verwendet. Der Name des Service auf der Linux-Maschine heißt //keycloak. // \\ Die //Logs//  sind unter dem folgenden Pfad zu finden: ///keycloak-12.0.2/standalone/log/server.log// \\ Die Keycloak-Installation befindet sich im Ordner keycloak-//akt. Versionsnummer//. Keycloak wird im Modus //Standalone//  ausgeführt (in diesem Ordner befindet sich auch die entsprechende Konfiguration). \\ Es gibt einen //Realm//  (=Sammlung aller Einstellungen und Konfigurationen) zum Testen (//lmz_dev//) und einen, der live ist (//lmz_prod//). Die Konfiguration ist größtenteils auch über ein User Interface möglich (z.B. Anlegen neuer User): \\ [[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]] (Konfiguration aller Realms möglich) \\ +Der Keycloak-Server wird zur //Benutzerverwaltung//  für die User:innen der Webseite verwendet. Der Name des Service auf der Linux-Maschine heißt //keycloak. // \\ Die //Logs//  sind unter dem folgenden Pfad zu finden: ///keycloak-12.0.2/standalone/log/server.log// \\ Die Keycloak-Installation befindet sich im Ordner keycloak-//akt. Versionsnummer//. Keycloak wird im Modus //Standalone//  ausgeführt (in diesem Ordner befindet sich auch die entsprechende Konfiguration). \\ Es gibt einen //Realm//  (=Sammlung aller Einstellungen und Konfigurationen) zum Testen (//lmz_dev//) und einen, der live ist (//lmz_prod//). Die Konfiguration ist größtenteils auch über ein User Interface möglich (z.B. Anlegen neuer User:innen): \\ [[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]] (Konfiguration aller Realms möglich) \\ 
-[[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]]Die Zugangsdaten dazu findet man im //Keepass//. Das Aussehen der Login Pagesowie der Userprofile muss über Keycloak und nicht über das Frontend angepasst werden (Ordner Themes).+[[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]] Die Zugangsdaten dazu findet man im //Keepass//. Das Aussehen der Login Page sowie der Userprofile muss über Keycloak und nicht über das Frontend angepasst werden (Ordner Themes).
  
 ===== Dokumentation Postgres ===== ===== Dokumentation Postgres =====
  
-Postgres ist das //DBMS//, das wir sowohl für unser Backend als auch für die Minetest-Server nutzen. Es hat keinen eigenen Servicenamen wie z.B. Keycloak. Die Verwaltung geschieht mittels folgendem command: \\ //''<nowiki>sudo pg_ctlcluster 13 main (reload|start|restart)</nowiki>''  //Die Logs liegen unter ''<nowiki>_/var/log/postgresql/postgresql-13-main.log_</nowiki>''In Postgres hat jede Welt ihre eigene Datenbank, welche 7 Tabellen enthält. Außerdem gibt es noch eine Datenbank, auf der unser Backend seine Daten zu angelegten Klassenzimmern verwaltet.+Postgres ist das //DBMS//, das wir sowohl für unser Backend als auch für die Minetest-Server nutzen. Es hat keinen eigenen Servicenamen wie z.B. Keycloak. Die Verwaltung geschieht mittels folgendem command: \\ //''<nowiki>sudo pg_ctlcluster 13 main (reload|start|restart)</nowiki>''  //Die Logs liegen unter ''<nowiki>_/var/log/postgresql/postgresql-13-main.log_</nowiki>''In Postgres hat jede Welt ihre eigene Datenbank, welche 7 Tabellen enthält. Außerdem gibt es noch eine Datenbank, auf der unser Backend seine Daten zu angelegten Lernräumen verwaltet.
  
 Der Zugriff auf die Postgres-Datenbank geschieht über SSH. Mittels //''<nowiki>sudo -u postgres psql</nowiki>''  //  kann auf die Datenbank zugegriffen werden. Mit //\l//  werden alle Datenbanken angezeigt. Mit //\c datenbankName//  kann eine Verbindung zu einer bestimmten Datenbank hergestellt werden. Mit //\d//  können die enthaltenen Tabellen angezeigt werden. Der Zugriff auf die Postgres-Datenbank geschieht über SSH. Mittels //''<nowiki>sudo -u postgres psql</nowiki>''  //  kann auf die Datenbank zugegriffen werden. Mit //\l//  werden alle Datenbanken angezeigt. Mit //\c datenbankName//  kann eine Verbindung zu einer bestimmten Datenbank hergestellt werden. Mit //\d//  können die enthaltenen Tabellen angezeigt werden.
Zeile 205: Zeile 205:
 SELECT * FROM (SELECT d.datacl, d.datname, w.* FROM pg_database AS d FULL JOIN worlds AS w ON "w"."worldId" = substring(d.datname, 2)::INTEGER \\ WHERE datistemplate = false AND datname LIKE 'k%') AS all_databases WHERE port IS NULL OR datname IS NULL ORDER BY datname; SELECT * FROM (SELECT d.datacl, d.datname, w.* FROM pg_database AS d FULL JOIN worlds AS w ON "w"."worldId" = substring(d.datname, 2)::INTEGER \\ WHERE datistemplate = false AND datname LIKE 'k%') AS all_databases WHERE port IS NULL OR datname IS NULL ORDER BY datname;
  
-Das Command gleicht die Datenbanken der Klassenzimmer mit den Einträgen in unserer Backenddata-Datenbank ab und gibt die Deltas aus.+Das Command gleicht die Datenbanken der Lernräume mit den Einträgen in unserer Backenddata-Datenbank ab und gibt die Deltas aus.
  
-===== Minetest=====+===== Minetest =====
  
-Der Name der Services der einzelnen Klassenzimmer ergibt sich nach dem folgenden Service: ''<nowiki>_k_<</nowiki>''  //klassenzimmerID>// \\ Die Logs liegen In der Datei //''<nowiki>debug.txt</nowiki>''  //  im jeweiligen Klassenzimmerordner unter ///home/awp/minetest-live/worlds/<html><userID></html>/<html><klassenzimmerID></html>//. Dabei ist die userID die ID des Accounts aus Keycloak. Im Ordner des Klassenzimmers befinden sich außerdem alle zugehörigen Konfigurationsdateien.+Der Name der Services der einzelnen Lernräume ergibt sich nach dem folgenden Service: ''<nowiki>_k_<</nowiki>''  //klassenzimmerID>// \\ Die Logs liegen In der Datei //''<nowiki>debug.txt</nowiki>''  //  im jeweiligen Lernraumordner unter ///home/awp/minetest-live/worlds/<html><userID></html>/<html><klassenzimmerID></html>//. Dabei ist die userID die ID des Accounts aus Keycloak. Im Ordner der Lernraum befinden sich außerdem alle zugehörigen Konfigurationsdateien.
  
 Im Home Verzeichnis AWP (//''<nowiki>/home/awp</nowiki>''  //) befindet sich im Ordner //minetest-live//  die aktuelle verwendete Minetest-Installation, dort befinden sich im Ordner ///mods//  die aktuell global installierten Mods. Eine Dokumentation über die installierten Mods ist [[:mod_uebersicht|]] verfügbar. Im Home Verzeichnis AWP (//''<nowiki>/home/awp</nowiki>''  //) befindet sich im Ordner //minetest-live//  die aktuelle verwendete Minetest-Installation, dort befinden sich im Ordner ///mods//  die aktuell global installierten Mods. Eine Dokumentation über die installierten Mods ist [[:mod_uebersicht|]] verfügbar.
  
-Jede Welt hat eine eigene //Postgres-Datenbank//  in der die Ingame Daten (Spielerinventar, Zugangsdaten, Blöcke der Welt, etc.) gespeichert werden (die Zugangsdaten sind in der jeweiligen world.mt zu finden (oder in der Passwortdatenbank siehePostgres).+Jede Welt hat eine eigene //Postgres-Datenbank//  in der die Ingame Daten (Spielerinventar, Zugangsdaten, Blöcke der Welt, etc.) gespeichert werden (die Zugangsdaten sind in der jeweiligen world.mt zu finden (oder in der Passwortdatenbank siehe Postgres).
  
 Jede Welt hat in Systemd einen eigenen Service. Jede Welt hat in Systemd einen eigenen Service.
Zeile 246: Zeile 246:
 ++++ ++++
  
-===== Zertifikate=====+===== Zertifikate =====
  
 Die Zertifikate für das Backend wurden mit folgendem Kommando erstellt: Die Zertifikate für das Backend wurden mit folgendem Kommando erstellt:
Zeile 286: Zeile 286:
 Die Anwendung greift auf Daten aus vier Quellen zu. Die Anwendung greift auf Daten aus vier Quellen zu.
  
-^Quellenname  ^Beschreibung  | +^ Quellenname                       ^ Beschreibung                                                                                                                                 ^ 
-|Keycloakdaten  |Hier werden alle Daten des Benutzers gespeichert (Name, Schule, Passwort), diese werden im Normalfall nicht durch die Anwendung verändert +| Keycloakdaten                     | Hier werden alle Daten der Benutzenden gespeichert (Name, Schule, Passwort), diese werden im Normalfall nicht durch die Anwendung verändert 
-|Datenbank "Backendata"  |Hier werden die zur (Klassenzimmer)verwaltung benötigten Informationen gespeichert  +| Datenbank "Backendata"            | Hier werden die zur (Lernraum)verwaltung benötigten Informationen gespeichert                                                                
-|Datenbanken "k**"  |Jede Welt besitzt eine eigene Datenbank auf der spielrelevanten Informationen gespeichert werden (z.B. Spielpasswörter, Inventar)  +| Datenbanken "k**"                 | Jede Welt besitzt eine eigene Datenbank auf der spielrelevanten Informationen gespeichert werden (z.B. Spielpasswörter, Inventar)            
-|Verzeichnis minetest-live/worlds  |Hier werden die nötigen Konfigurationsinformationen zu den Klassenzimmer gespeichert (Mods, Spawnpoint, etc.)  |+| Verzeichnis minetest-live/worlds  | Hier werden die nötigen Konfigurationsinformationen zu den Lernräumen gespeichert (Mods, Spawnpoint, etc.)                                   |
  
 Die Template Datenbank wird als Template markiert und Connections werden verboten, da die Datenbank bei bestehenden Verbindung nicht als Template verwendet werden kann. \\ Dies haben wir mit den folgenden Commands eingerichtet: Die Template Datenbank wird als Template markiert und Connections werden verboten, da die Datenbank bei bestehenden Verbindung nicht als Template verwendet werden kann. \\ Dies haben wir mit den folgenden Commands eingerichtet:
Zeile 300: Zeile 300:
 ===== Dokumentation Tests ===== ===== Dokumentation Tests =====
  
-Zum Testen des Backends existiert eine Postman Collection mit eingerichteten Tests. Diese können ganz einfach über den Collection-Runner ausgeführt werden (Zugriff muss angefragt werden – Nutzeranzahl leider begrenzt). \\ Das Frontend muss aktuell noch manuell getestet werden.+Zum Testen des Backends existiert eine Postman Collection mit eingerichteten Tests. Diese können ganz einfach über den Collection-Runner ausgeführt werden (Zugriff muss angefragt werden – Nutzer:innenanzahl leider begrenzt). \\ Das Frontend muss aktuell noch manuell getestet werden.