Both sides previous revisionPrevious revisionNext revision | Previous revision |
en:intern:doku:technische_dokumentation [2022/10/05 22:56] – [Ablauf eingehender Requests] frederike_lmz | en:intern:doku:technische_dokumentation [2022/10/12 18:55] (current) – steffi_lmz |
---|
With the help of the Tartarus backup solution, the data from the AWP directory is automatically backed up in Hetzner’s Storage Box. This solution was chosen because the servers are already contracted with Hetzner and the backup storage was supplied free of charge. | With the help of the Tartarus backup solution, the data from the AWP directory is automatically backed up in Hetzner’s Storage Box. This solution was chosen because the servers are already contracted with Hetzner and the backup storage was supplied free of charge. |
| |
The //''<nowiki>tartarus</nowiki>'' // command starts the backup. A configuration file needs to be defined. A configuration file must still be specified. For different backup profiles, these are located under //''<nowiki>/etc/tartarus/*.conf</nowiki>'' //. They contain the information, which directory is backed up and where Tartarus stores the markers for the incremental backups. The marker files are maintained by Tartarus itself, but a path to the marker file must be created for each backup profile beforehand. For the backup profile of the Minetest directory it looks like this: | The //''<nowiki>tartarus</nowiki>'' // command starts the backup. A configuration file needs to be defined. A configuration file must still be specified. For different backup profiles, these are located under //''<nowiki>/etc/tartarus/*.conf</nowiki>'' //. They contain the information, which directory is backed up and where Tartarus stores the markers for the incremental backups. The marker files are maintained by Tartarus itself, but a path to the marker file must be created for each backup profile beforehand. For the backup profile of the Minetest directory it looks like this: |
| |
''<nowiki>/var/spool/tartarus/timestamps/backupprofilname</nowiki>'' When creating a new backup profile, the path must be adjusted. | ''<nowiki>/var/spool/tartarus/timestamps/backupprofilname</nowiki>'' When creating a new backup profile, the path must be adjusted. |
''<nowiki>_sudo tartarus -i /etc/tartarus/Name der Backupprofilkofgurationsdatei_</nowiki>'' creates an incremental backup according to the specified configuration profile. | ''<nowiki>_sudo tartarus -i /etc/tartarus/Name der Backupprofilkofgurationsdatei_</nowiki>'' creates an incremental backup according to the specified configuration profile. |
| |
To perform a cleanup of the storage box after each backup, the script c//haron.ftp// invoked automatically under ///usr/sbin// / after Tartarus. . This deletes all backups older than 13 days belonging to the same profile after the new backup is created. This ensures that the storage space of the Storage Box is cleared again. In the /etc/tartarus/''<nowiki>_generic.inc_</nowiki>'' a hook was inserted for this. There you could also define the maximum age. Complete backups can only be deleted if all incremental backups based on them have been deleted. With the Hetzner administration robot [[https://robot.your-server.de/storage|https://robot.your-server.de/storage]] you could check the used storage space. It is important to note that Hetzner’s robot only updates every 15 minutes. | To perform a cleanup of the storage box after each backup, the script c//haron.ftp// invoked automatically under ///usr/sbin// / after Tartarus. . This deletes all backups older than 13 days belonging to the same profile after the new backup is created. This ensures that the storage space of the Storage Box is cleared again. In the /etc/tartarus/''<nowiki>_generic.inc_</nowiki>'' a hook was inserted for this. There you could also define the maximum age. Complete backups can only be deleted if all incremental backups based on them have been deleted. With the Hetzner administration robot [[https://robot.your-server.de/storage|https://robot.your-server.de/storage]] you could check the used storage space. It is important to note that Hetzner’s robot only updates every 15 minutes. |
| |
To access the content from the server, the backup storage has been mounted at _/home/awp/backups_. Use _sudo crontab -l_ to view the current automation. With sudo crontab -e the automation can be adjusted. | To access the content from the server, the backup storage has been mounted at _/home/awp/backups_. Use _sudo crontab -l_ to view the current automation. With sudo crontab -e the automation can be adjusted. |
The web interface can only be used if monitoring has been started. Check-MK uses the "open monitoring distribution" (omd) for monitoring. OMD can create instances, so called sites, with which you can monitor the server independently. Currently an instance has been created, which has been named "monitoring". To start the monitoring on this instance, execute the command //omd start monitoring// . The instance can also be stopped again with the command //omd stop monitoring// . | The web interface can only be used if monitoring has been started. Check-MK uses the "open monitoring distribution" (omd) for monitoring. OMD can create instances, so called sites, with which you can monitor the server independently. Currently an instance has been created, which has been named "monitoring". To start the monitoring on this instance, execute the command //omd start monitoring// . The instance can also be stopped again with the command //omd stop monitoring// . |
| |
Once the instance is started, the web interface can be accessed via [[http://minetest.lmz-bw.de/monitoring|http://minetest.lmz-bw.de/monitoring]]. | Once the instance is started, the web interface can be accessed via [[http://minetest.lmz-bw.de/monitoring|http://minetest.lmz-bw.de/monitoring]]. |
| |
Hosts: | Hosts: |
| |
Access: | Access: |
| |
* ssh address: 188.40.113.24 or [[http://minetest.lmz-bw.de/|minetest.lmz-bw.de]] (access: //awp user server// or //root user server// in the keepass) | * ssh address: 188.40.113.24 or [[http://minetest.lmz-bw.de/|minetest.lmz-bw.de]] (access: //awp user server// or //root user server// in the keepass) |
| |
The interface is a rest interface that is used to provide required data and functionality using the HTTP methods. | The interface is a rest interface that is used to provide required data and functionality using the HTTP methods. |
| |
Using [[https://www.minetest.lmz-bw.de:1234/api-docs|https:<nowiki>//</nowiki>minetest.lmz-bw.de:1234/api-docs]] a documentation of the currently available endpoints based on the [[http://spec.openapis.org/oas/v3.0.3|Open API 3.0.3]] standard was created with the help of //swagger.// Authentication with a //[[https://oauth.net/2/bearer-tokens/#:~:text=Bearer%20Tokens%20are%20the%20predominant,such%20as%20JSON%20Web%20Tokens.|bearer token]]// is required to use the interface. | Using [[https://www.minetest.lmz-bw.de:1234/api-docs|https:<nowiki>//</nowiki>minetest.lmz-bw.de:1234/api-docs]] a documentation of the currently available endpoints based on the [[http://spec.openapis.org/oas/v3.0.3|Open API 3.0.3]] standard was created with the help of //swagger.// Authentication with a //[[https://oauth.net/2/bearer-tokens/#:~:text=Bearer%20Tokens%20are%20the%20predominant,such%20as%20JSON%20Web%20Tokens.|bearer token]]// is required to use the interface. |
| |
==== Technology ==== | ==== Technology ==== |
| |
The programming language used for the backend is [[https://www.typescriptlang.org/|//TypeScript//]] in version 4.1.3. For the interface we used [[http://expressjs.com/|Express]] version 4.17.1. The DBMS we used is //[[https://www.postgresql.org/|PostgreSQL]]//, since it also serves as the database for the Minetest servers. For user management we use a //[[https://www.keycloak.org/|keycloak]]// server, which runs on version 12. | The programming language used for the backend is [[https://www.typescriptlang.org/|//TypeScript//]] in version 4.1.3. For the interface we used [[http://expressjs.com/|Express]] version 4.17.1. The DBMS we used is //[[https://www.postgresql.org/|PostgreSQL]]//, since it also serves as the database for the Minetest servers. For user management we use a //[[https://www.keycloak.org/|keycloak]]//server, which runs on version 12. |
| |
| |
==== Versioning ==== | ==== Versioning ==== |
| |
The code for the backend was versioned using //Git//. You find the complete commit history [[https://github.com/blockalot/Backend|on GitHub]]. It should be noted that the current state of development is in the //main// branch. In the //live// branch is the current running state. It is available [[https://www.minetest.lmz-bw.de:1234|here]]. | The code for the backend was versioned using //Git//. You find the complete commit history [[https://github.com/blockalot/Backend|on GitHub]]. It should be noted that the current state of development is in the //main// branch. In the //live// branch is the current running state. It is available [[https://www.minetest.lmz-bw.de:1234|here]]. |
| |
| |
==== Pipeline ==== | ==== Pipeline ==== |
The first is a quality assurance pipeline. It executes the following commands in the order given: | The first is a quality assurance pipeline. It executes the following commands in the order given: |
| |
- npm ci → check the deployed [[https://docs.npmjs.com/cli/v6/commands/npm-ci|dependencies]] | - npm ci → check the deployed [[https://docs.npmjs.com/cli/v6/commands/npm-ci|dependencies]] |
- npm run lint:ci → Check code quality using [[https://eslint.org/|ESLint]] | - npm run lint:ci → Check code quality using [[https://eslint.org/|ESLint]] |
| |
- //npx tsc →// compiling with TypeScript Compiler | - //npx tsc →// compiling with TypeScript Compiler |
- //systemctl –user start prod_backend →// restart the Linux service | - //systemctl –user start prod_backend →// restart the Linux service |
| In addition, a pre-commit hook was set up with //[[https://www.npmjs.com/package/husky|Husky]]//that executes the command //npm run lint:ci// before every attempted commit. This is to prevent code with insufficient code quality from ending up in the repository. |
In addition, a pre-commit hook was set up with //[[https://www.npmjs.com/package/husky|Husky]]// that executes the command //npm run lint:ci// before every attempted commit. This is to prevent code with insufficient code quality from ending up in the repository. | |
| |
==== Authentification ==== | ==== Authentification ==== |
| |
In order to successfully authenticate on the backend, you must first fetch a token from our keycloak server [[https://www.minetest.lmz-bw.de:8443/auth/realms/lmz_prod/protocol/openid-connect/token|here]]. This requires a POST request with the content type //application/x-www-form-urlencoded// with the following payload: | In order to successfully authenticate on the backend, you must first fetch a token from our keycloak server [[https://www.minetest.lmz-bw.de:8443/auth/realms/lmz_prod/protocol/openid-connect/token|here]]. This requires a POST request with the content type //application/x-www-form-urlencoded// with the following payload: |
| |
* grant_type: password | * grant_type: password |
* client_id <html><client ID></html> → the client we currently use for the frontend is called //vue-client// | * client_id <html><client ID></html> → the client we currently use for the frontend is called //vue-client// |
| |
If you enter the above data correctly, you will receive a //[[https://jwt.io/|JWT]]// in the response under the property //access_token// that must be sent with a request to the backend as //authorization header// in order to authenticate yourself. | If you enter the above data correctly, you will receive a //[[https://jwt.io/|JWT]]//in the response under the property //access_token// that must be sent with a request to the backend as //authorization header// in order to authenticate yourself. |
| |
==== Procedure of Incoming Requests ==== | ==== Procedure of Incoming Requests ==== |
==== Code Documentation ==== | ==== Code Documentation ==== |
| |
The code was annotated with comments in JSDoc format following the recommendation from the [[https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html|Empfehlung aus der TypeScript documentation]]. | The code was annotated with comments in JSDoc format following the recommendation from the [[https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html|Empfehlung aus der TypeScript documentation]]. |
| |
===== Dokumentation Website ===== | ===== Documentation Website ===== |
| |
Das Frontend von Blockalot ist der Teil der Anwendung, den die Endnutzer bedienen, um ihre Klassenzimmer zu verwalten. | Blockalot’s frontend is the part of the application that end users operate to manage their BLOCKALOTSpaces. |
| |
==== 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. | The website design is based on the corporate design of the LMZ: The colors, especially orange and olive green, of the LMZ homepage were adopted. The logo and some graphics were also adopted or modified. For some elements, for example, for the "cards" of the BLOCKALOTSpaces on the dashboard, we used //neumorphism//. While this provides a modern look, its suitability, especially in terms of contrast, should be further reviewed. |
| |
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. | A mockup for the website was created using //Figma//. It can be viewed [[https://www.figma.com/file/hDVSUEyJKd6Oij7IlE01A1/Mockup?node-id=0%3A1|here]]. If changes need to be made, please contact //rech1033@hs-karlsruhe.de// for access. |
| |
Die auf der Website verwendeten Farben sind in der Datei //src/css/colors.css// als globale Variablen definiert. Dies ermöglicht, dass Änderungen an diesen Farbcodes die entsprechenden Farben auf der gesamten Website ändern. Somit könnte die Anwendung zum Beispiel mit geringem Aufwand an ein anderes Corporate Design angepasst werden. Außerdem kann hierdurch die Implementierung eines "Darkmodes" umgesetzt werden, für welchen schon ein Beispiel im Mockup zu finden ist. | The colors used on the website are defined as global variables in the //src/css/colors.css// file. This allows changes to these color codes to change the corresponding colors throughout the site. Thus, for example, the application could be adapted to a different corporate design with little effort. In addition, the implementation of a "darkmode" can be realized, for which an example can already be found in the mockup. |
| |
==== Technologie ==== | ==== Technology ==== |
| |
Das Frontend ist mit dem //JavaScript-Framework// //Vue// in der Version 3.0.0 geschrieben. Zum //State-Management// wurde //Vuex// benutzt. Dabei wurde versucht, auf externen Code zu verzichten, um Abhängigkeiten zu reduzieren. | The frontend is written with the //JavaScript framework// //Vue// in version 3.0.0. //Vuex// was used for //state management//. We tried to avoid external code to reduce dependencies. |
| |
==== Versionierung ==== | ==== Versioning ==== |
| |
Alle Abhängigkeiten und deren Versionen können im [[https://github.com/blockalot/Frontend/network/dependencies|Repository auf Github]] beziehungsweise in der Datei //package.json// eingesehen werden. Außerdem wurde dort mithilfe von //GitHub Actions// analog zum Backend eine Pipeline zur Qualitätssicherung und zum automatischen Deployment eingerichtet. | You can view all dependencies and their versions in [[https://github.com/blockalot/Frontend/network/dependencies|repository on Github]] or in the //package.json// file. In addition, a pipeline for quality assurance and automatic deployment has been set up there using //GitHub Actions//, analogous to the backend. |
| |
==== Aufbau ==== | ==== Structure ==== |
| |
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). | The root file is //src/App.vue//. This includes the //navbar//, the //footer// and the current //view//. The current view is determined by //Vue-Router//, the corresponding file is //src/router/index.js//. The views are located in //src/views// and correspond to the different pages of the application (Home, Dashboard, FAQ, BLOCKALOTSpaces, Imprint and Data Protection). |
| |
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]]). | The views include different components that are stored in // src/components//. Some of these components, for example the button, can be reused throughout the frontend. //Vuese// can be used to generate more information about each component. //Vuese// automatically generates documentation for the components. The generated files are written in //Markdown// and are located in //website/components//. A website can be hosted locally that displays all //Markdown// files of the component documentation in a formatted way. For this, you need to install //Vuese// globally and then run //vuese serve -open// (see [[https://vuese.org/cli|Vuese documentation]]). |
| |
Der //Store// (State-Management) ist in //src/store/index.js// definiert. Hier werden //State-Manipulationen// durchgeführt und //API-Calls// aus der Datei //src/api/api.js// aufgerufen. Diese sind für die Kommunikation mit dem Backend zuständig. | The //store// (state management) is defined in //src/store/index.js//. This is where //state manipulations// are performed and// API calls// is activated from the //src/api/api.js// file. These are responsible for communication with the backend. |
| |
Die Funktionen für die Passwort- und PDF-Generierung sind in den Ordner //src/functions// ausgelagert, um den Code übersichtlicher zu machen. Alle Grafiken liegen unter //src/assets.// | The password and PDF generation functions are stored in the //src/functions// folder to make the code more concise. All graphics are located in //src/assets//. |
| |
===== Dokumentation Keycloak ===== | ===== Documentation 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) \\ | The keycloak server is used for the //user management// of the website. The name of the service on the Linux machine is //keycloak//. The //logs// can be found using the following path: ///keycloak-12.0.2/standalone/log/server.log// \\ The keycloak installation is located in the folder keycloak-//akt. Version number//. Keycloak is run in //standalone// mode (the corresponding configuration is also located in this folder). \\ There is a //realm// (= collection of all settings and configurations) for testing (//lmz_dev//) and one that is live (//lmz_prod//). The configuration can also mostly be done via a user interface (e.g. creating new users): \\ [[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]] (configuration of all realms possible) \\ |
[[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). | [[https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/|https://minetest.lmz-bw.de:8443/auth/admin/lmz_prod/console/]] You find the access data for this in the //keepass//. The appearance of the login page as well as the user profiles must be customized via Keycloak and not via the frontend (folder themes). |
| |
===== Dokumentation Postgres ===== | ===== Documentation 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 is the //DBMS// we use for both our backend and Minetest servers. It does not have its own service name, such as Keycloak. It is managed using the following command: \\ //''<nowiki>sudo pg_ctlcluster 13 main (reload|start|restart)</nowiki>'' // sudo pg_ctlcluster 13 main (reload|start|restart) The logs are located at ''<nowiki>_/var/log/postgresql/postgresql-13-main.log_</nowiki>'' In Postgres, each world has its own database that contains seven tables. There is also another database where our backend manages its data on created BLOCKALOTSpaces. |
| |
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. | The access to the Postgres database is done via SSH. With The access to the Postgres database is done via SSH. With sudo -u postgres psql the database can be accessed. With //''<nowiki>sudo -u postgres psql</nowiki>'' // the database can be accessed. With //\l// all databases are displayed. With //\c databaseName// you create a connection to a specific database. With //\d// the contained tables can be displayed. |
| |
Zur bequemeren Verwaltung kann über //pgAdmin// auf die Datenbank zugegriffen werden. Hierzu ist eine lokale Installation sowie ein Hinterlegen der IP-Adresse in der Config-Datei unter ///etc/postgresql/13/main/pg_hba.conf// notwendig. Hierzu muss die IP-Adresse unten angehängt werden (nach dem Muster der vorhandenen Einträge). Danach muss die Konfiguration mit dem Command //''<nowiki>sudo pg_ctlcluster 13 main reload</nowiki>'' // neu geladen werden. | For a more convenient administration, the database can be accessed via //pgAdmin//. For this, a local installation as well as a depositing of the IP address in the Config file in ///etc/postgresql/13/main/pg_hba.conf// is necessary. For this, the IP address must be attached below (following the pattern of the existing entries). After that a reload of the configuration with the command //''<nowiki>sudo pg_ctlcluster 13 main reload</nowiki>'' // is necessary. |
| |
In unserer Datenbank vom Backend können u.U. inkonsistente Datenbestände durch Fehler beim Testen entstanden sein. Diese können mit dem folgenden Command ermittelt werden: | In our backend database, inconsistent data may have resulted from errors during testing. These can be traced with the following command: |
| |
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. | The command matches the databases of the BLOCKALOTSpaces with the entries in our backend database and displays the deltas. |
| |
===== 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. | The name of the services of each BLOCKALOTSpace is derived from the following service: ''<nowiki>_k_<</nowiki>'' //klassenzimmerID>// \\ The logs are located In the //''<nowiki>debug.txt</nowiki>'' // file in the respective BLOCKALOTSpace folder in ///home/awp/minetest-live/worlds/<html><userID></html>/<html><classroomID></html>//. Here, the userID is the ID of the account from Keycloak. The BLOCKALOTSpace folder also contains all the associated configuration files. |
| |
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. | The current used Minetest installation is located in the home directory AWP (//''<nowiki>/home/awp</nowiki>'' //) in the folder //minetest-live//. In the folder ///mods//, you find the current globally installed mods. Find documentation about the installed mods in [[:mod_uebersicht|]] . |
| |
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). | Each world has its own //postgres database// in which the ingame data (player inventory, access data, blocks of the world, etc.) is stored (the access data can be found in the respective world.mt (or in the password database see Postgres). |
| |
Jede Welt hat in Systemd einen eigenen Service. | Each world has its own service in Systemd. |
| |
Weitere Infos: | More information: |
| |
++++Die Installation ist folgendermaßen erfolgt: | | ++++The installation is done as follows: | |
| |
Navigiere in den gewünschten Ordner | Navigate to the desired folder |
<code> | <code> |
| |
</code> | </code> |
| |
Aktuelle Version: **stable-5** | Current version: **stable-5** |
| |
<code> | <code> |
++++ | ++++ |
| |
===== Zertifikate: ===== | ===== Certificates ===== |
| |
Die Zertifikate für das Backend wurden mit folgendem Kommando erstellt: | The certificates for the backend were created with the following command: |
| |
sudo certbot –apache -d [[http://minetest.lmz-bw.de/|minetest.lmz-bw.de]] | sudo certbot –apache -d [[http://minetest.lmz-bw.de/|minetest.lmz-bw.de]] |
Saving debug log to /var/log/letsencrypt/letsencrypt.log | Saving debug log to /var/log/letsencrypt/letsencrypt.log |
| |
Renewing an existing certificate Created an SSL vhost at /etc/apache2/sites-available/000-default-le-ssl.conf Enabled Apache socache_shmcb module Enabled Apache ssl module Deploying Certificate to VirtualHost /etc/apache2/sites-available/000-default-le-ssl.conf Enabling available site: /etc/apache2/sites-available/000-default-le-ssl.conf | Renewing an existing certificate Created an SSL vhost at /etc/apache2/sites-available/000-default-le-ssl.conf Enabled Apache socache_shmcb module Enabled Apache ssl module Deploying Certificate to VirtualHost /etc/apache2/sites-available/000-default-le-ssl.conf Enabling available site: /etc/apache2/sites-available/000-default-le-ssl.conf |
| |
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: No redirect - Make no further changes to the webserver configuration. 2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for new sites, or if you're confident your site works on HTTPS. You can undo this change by editing your web server's configuration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2 Redirecting vhost in /etc/apache2/sites-enabled/000-default.conf to ssl vhost in /etc/apache2/sites-available/000-default-le-ssl.conf | Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 1: No redirect - Make no further changes to the webserver configuration. 2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for new sites, or if you're confident your site works on HTTPS. You can undo this change by editing your web server's configuration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2 Redirecting vhost in /etc/apache2/sites-enabled/000-default.conf to ssl vhost in /etc/apache2/sites-available/000-default-le-ssl.conf |
| |
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Your existing certificate has been successfully renewed, and the new certificate has been installed. | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Your existing certificate has been successfully renewed, and the new certificate has been installed. |
| |
The new certificate covers the following domains: minetest.lmz-bw.de | The new certificate covers the following domains: minetest.lmz-bw.de |
| |
You should test your configuration at: [[https://www.ssllabs.com/ssltest/analyze.html?d=minetest.lmz-bw.de|https://www.ssllabs.com/ssltest/analyze.html?d=minetest.lmz-bw.de]] | You should test your configuration at: [[https://www.ssllabs.com/ssltest/analyze.html?d=minetest.lmz-bw.de|https://www.ssllabs.com/ssltest/analyze.html?d=minetest.lmz-bw.de]] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | |
| |
IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/minetest.lmz-bw.de/privkey.pem Your cert will expire on 2021-04-07. To obtain a new or tweaked version of this certificate in the future, simply run certbot again with the "certonly" option. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: | IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/minetest.lmz-bw.de/privkey.pem Your cert will expire on 2021-04-07. To obtain a new or tweaked version of this certificate in the future, simply run certbot again with the "certonly" option. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: |
| |
Donating to ISRG / Let's Encrypt: [[https://letsencrypt.org/donate|https://letsencrypt.org/donate]] | Donating to ISRG / Let's Encrypt: [[https://letsencrypt.org/donate|https://letsencrypt.org/donate]] Donating to EFF: [[https://eff.org/donate-le|https://eff.org/donate-le]] |
Donating to EFF: [[https://eff.org/donate-le|https://eff.org/donate-le]] | |
| |
Diese Zertifikat wurden mit folgenden Anweisungen für Keycloak verwendet (eventuell direkt Pfad anpassen): | This certificate was used with the following instructions for Keycloak (possibly adjust path directly): |
| |
[[https://ordina-jworks.github.io/security/2019/08/14/Using-Lets-Encrypt-Certificates-In-Java.html|https://ordina-jworks.github.io/security/2019/08/14/Using-Lets-Encrypt-Certificates-In-Java.html]] | [[https://ordina-jworks.github.io/security/2019/08/14/Using-Lets-Encrypt-Certificates-In-Java.html|https://ordina-jworks.github.io/security/2019/08/14/Using-Lets-Encrypt-Certificates-In-Java.html]] |
[[https://www.keycloak.org/docs/11.0/server_installation/index.html#_start_cli|https://www.keycloak.org/docs/11.0/server_installation/index.html#_start_cli]] | [[https://www.keycloak.org/docs/11.0/server_installation/index.html#_start_cli|https://www.keycloak.org/docs/11.0/server_installation/index.html#_start_cli]] |
| |
openssl pkcs12 -export -in /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem -inkey /etc/letsencrypt/live/minetest.lmz-bw.de/privkey.pem -out /tmp/minetest.lmz-bw.de_2.p12 -name <nowiki>http://minetest.lmz-bw.de/</nowiki> -CAfile /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem -caname "Let's Encrypt Authority X3" -password pass:changeit | openssl pkcs12 -export -in /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem -inkey /etc/letsencrypt/live/minetest.lmz-bw.de/privkey.pem -out /tmp/minetest.lmz-bw.de_2.p12 -name <nowiki>http://minetest.lmz-bw.de/</nowiki> -CAfile /etc/letsencrypt/live/minetest.lmz-bw.de/fullchain.pem -caname "Let's Encrypt Authority X3" -password pass:changeit |
| |
keytool -importkeystore -deststorepass changeit -destkeypass changeit -deststoretype pkcs12 -srckeystore /tmp/minetest.lmz-bw.de_2.p12 -srcstoretype PKCS12 -srcstorepass changeit -destkeystore /tmp/minetest.lmz-bw.de_2.keystore -alias minetest.lmz-bw.de/%% | keytool -importkeystore -deststorepass changeit -destkeypass changeit -deststoretype pkcs12 -srckeystore /tmp/minetest.lmz-bw.de_2.p12 -srcstoretype PKCS12 -srcstorepass changeit -destkeystore /tmp/minetest.lmz-bw.de_2.keystore -alias minetest.lmz-bw.de/%% |
| |
===== Datenmodell ===== | ===== Data Model ===== |
| |
Die Anwendung greift auf Daten aus vier Quellen zu. | The application accesses data from four sources. |
| |
^Quellenname ^Beschreibung | | ^Source Name^Description | |
|Keycloakdaten |Hier werden alle Daten des Benutzers gespeichert (Name, Schule, Passwort), diese werden im Normalfall nicht durch die Anwendung verändert | | |Keycloak data |All user data is stored here (name, school, password), this is usually not changed by the application | |
|Datenbank "Backendata" |Hier werden die zur (Klassenzimmer)verwaltung benötigten Informationen gespeichert | | |Database "Backendata" |This is where the information needed for (BLOCKALOTSpace) administration is stored.| |
|Datenbanken "k**" |Jede Welt besitzt eine eigene Datenbank auf der spielrelevanten Informationen gespeichert werden (z.B. Spielpasswörter, Inventar) | | |Databases "k**" |Each world has its own database where game relevant information is stored (e.g. game passwords, inventory) | |
|Verzeichnis minetest-live/worlds |Hier werden die nötigen Konfigurationsinformationen zu den Klassenzimmer gespeichert (Mods, Spawnpoint, etc.) | | |Directory minetest-live/worlds |This is where the necessary configuration information for the BLOCKALOTSpaces is stored (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: | The template database is marked as a template and connections are forbidden, because the database cannot be used as a template if a connection exists. \\ We have set this up with the following commands: |
| |
UPDATE pg_database SET datistemplate = true where datname = 'minetest_template1'; | UPDATE pg_database SET datistemplate = true where datname = 'minetest_template1'; |
UPDATE pg_database SET datallowconn = false where datname = 'minetest_template1'; | UPDATE pg_database SET datallowconn = false where datname = 'minetest_template1'; |
| |
===== Dokumentation Tests ===== | ===== Documentation 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. | For testing the backend there is a Postman Collection with configured tests. These can be easily run with the collection runner (access must be requested – unfortunately, number of users is limited). \\ The frontend requires manual testing at the moment. |
| |
| |