Technical Documentation

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 tartarus 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 /etc/tartarus/*.conf . 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:

/var/spool/tartarus/timestamps/backupprofilname When creating a new backup profile, the path must be adjusted.

The generic.inc file contains the most important settings regarding the connection to the Hetzner server. In addition, the -i option can be used to switch to incremental instead of complete backups. For this, a complete backup must first be performed before an incremental backup can be started with the same profile.

_sudo tartarus /etc/tartarus/Name der Backupprofilkofgurationsdatei_ creates a backup according to the specified configuration profile.

_sudo tartarus -i /etc/tartarus/Name der Backupprofilkofgurationsdatei_ creates an incremental backup according to the specified configuration profile.

To perform a cleanup of the storage box after each backup, the script charon.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/_generic.inc_ 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 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. To adjust the automation use sudo crontab -e .

These two entries ensure that a backup is performed by Tartarus at 22:30. From Monday to Saturday these backups with the configuration profile are carried out incrementally. On Sundays a complete backup is performed with the configuration profile.

Use the CheckMK monitoring tool to monitor and check the most important services of the server. CheckMK can be operated via a web interface and can also be configured in this interface.

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.

Hosts:

CheckMK needs a host to monitor services. Here the Linux server with the IP address (188.40.113.24) was set up as host. Each host has a number of services that are automatically detected and monitored by CheckMK.

Services:

All currently monitored services are displayed on the home page. You can get the most important information about each monitored service immediately. If you click on the service name (for example, CPU load) you will get all the information about this service. Each service is assigned a state by the system which is derived from the rules defined for this service. The state is either ok, warn, crit, unknown or pend.

Klick on the menu button to automatically restart the check or display the check parameters. Click on with the graph icon to get one or more graphs that show you the evolution of the numbers for this service.

The graph shows an overview of the course of the service over the last 4 hours. You can change the graphic on the x-axis (time) as well as on the y-axis (CPU load) and also zoom in. So it is possible to display the graph you need. The threshold values are also displayed or when a value gets the status warning or critical. You can thus see how busy the service currently is.

Currently 20 services are monitored. To access all services or to monitor other services as well, you have to change the configuration in the Wato menu. To do this, click on Host in the Wato configuration and select the service icon for the “monitoring” host. In this menu, all detected services are displayed and you can enable or disable services as you wish. To change the rule for the status of a service, you have to adjust the check parameters with a new rule. To do this, click on the parameter icon and create a new rule with new values in the “main folder”

It is important to note that if something is changed or something is added, you still have to confirm this change before the change is made.

User:

You can view all users in the Wato menu under the User item. In this menu, you can create new users as well as edit current users. Currently the users cmkadmin and aufseher are configured. Both users have full administration rights and for both a mail address is entered. You can find the login data for both users in the password database.

Notification:

For both active users a mail address is registered. A mail is sent to these addresses as soon as the status of a service changes. The mail contains information about which service has changed and a graph that shows the development of the service over the last day. Both users are currently registered in the contact group “Everything”. If you do not want to be notified about every service you have to change the contact group in the Wato menu or create a new contact group.

Logs:

The different logs are stored by omd. They are stored in the folder /omd/sites/monitoring/var/log /.

Further Documentation:

You can find detailed documentation on all features of Checkmk here: https://docs.checkmk.com/latest/de/index.html

2 Servers:

• Webhosting (www.blockalot.de):

Services:

• Website
• Mail Server

Access:

• KonsoleH on https:<nowiki>//</nowiki>konsoleh.your-server.de (access data: KonsoleH in the keepass)

Backend Server (minetest.lmz-bw.de):

Services:

1. Minetest
2. Postgres database
3. Backend
4. Keycloak
5. CheckMK

Access:

• ssh address: 188.40.113.24 or minetest.lmz-bw.de (access: awp user server or root user server in the keepass)

The backend provides the required functionalities for the frontend via an interface.

The interface is a rest interface that is used to provide required data and functionality using the HTTP methods.

Using https:<nowiki>//</nowiki>minetest.lmz-bw.de:1234/api-docs a documentation of the currently available endpoints based on the Open API 3.0.3 standard was created with the help of swagger. Authentication with a bearer token is required to use the interface.

The programming language used for the backend is //TypeScript// in version 4.1.3. For the interface we used Express version 4.17.1. The DBMS we used is PostgreSQL, since it also serves as the database for the Minetest servers. For user management we use a keycloak server, which runs on version 12.

The code for the backend was versioned using Git. You find the complete commit history 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 here.

Two pipelines have been created using GitHub Actions.

The first is a quality assurance pipeline. It executes the following commands in the order given:

1. npm ci → check the deployed dependencies
2. npm run lint:ci → Check code quality using ESLint

With the help of the second pipeline, the code can be deployed on the currently used Linux machine at Hetzner. With each incoming commit on the branch live, a script is executed that transfers the code via FTP to the Linux server and executes the following commands:

1. systemctl –user stop prod_backend → stops the Linux service
2. npm install → download necessary dependencies
3. npx tsc → compiling with TypeScript Compiler
4. systemctl –user start prod_backend → restart the Linux service

In addition, a pre-commit hook was set up with 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.

Um sich am Backend erfolgreich zu authentifizieren, muss man sich zunächst einen Token bei unserem Keycloak-Server unter dieser URL abholen. Dazu muss ein POST-Request mit dem Content-Type application/x-www-form-urlencoded mit dem folgenden Payload gesendet werden:

• grant_type: password
• username: <html><Testuser></html>
• password: <html><Passwort></html>
• client_id <html><Client-ID></html> → der Client, den wir derzeit für das Frontend verwenden heißt vue-client

Gibt man die o.g. Daten richtig an, erhält man in der Response unter der Property access_token einen JWT, der bei einem Request an das Backend als Authorization-Header mitgeschickt werden muss, um sich zu authentifizieren.

Bei der Bearbeitung der eingehenden Requests wird der folgende Ablauf verwendet:

1. Parsing des Body mithilfe von express.json()
2. Sicherheitsüberprüfung des Requests mithilfe von helmet
3. Authentifizierung und Extrahieren der User ID aus dem Token → Custom Middleware unter /src/security/validatejwt.ts
4. Ausführung eines Handlers, der die Ablaufsteuerung für die Abarbeitung des Requests übernimmt → Handler-Funktionen unter /src/handler/<html><http-methode></html>-handler.ts
5. Ausführung der verschiedenen Services durch den Handler → Service-Funktionen unter /src/service
6. Error Handling → mithilfe eines Error-Handlers unter /src/handler/error-handler.ts
7. Senden einer entsprechenden Response

Der Code wurde nach der Empfehlung aus der TypeScript-Dokumentation mit Kommentaren im JSDoc-Format kommentiert.

Das Frontend von Blockalot ist der Teil der Anwendung, den die Endnutzer bedienen, um ihre Klassenzimmer zu verwalten.

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.

Ein Mockup für die Website wurde mit Figma erstellt. Über 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.

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.

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.

Alle Abhängigkeiten und deren Versionen können im 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.

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 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 Vuese-Dokumentation).

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.

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­.

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/ (Konfiguration aller Realms möglich)

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).

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:
sudo pg_ctlcluster 13 main (reload|start|restart) Die Logs liegen unter _/var/log/postgresql/postgresql-13-main.log_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.

Der Zugriff auf die Postgres-Datenbank geschieht über SSH. Mittels sudo -u postgres psql 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.

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 sudo pg_ctlcluster 13 main reload neu geladen werden.

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:

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.

Der Name der Services der einzelnen Klassenzimmer ergibt sich nach dem folgenden Service: _k_< klassenzimmerID>
Die Logs liegen In der Datei debug.txt 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.

Im Home Verzeichnis AWP (/home/awp ) 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 siehe. Postgres).

Jede Welt hat in Systemd einen eigenen Service.

Weitere Infos:

Die Installation ist folgendermaßen erfolgt:

export branch=$(printf "Enter Minetest version: ">&2;read r;echo "$r")

(sudo apt-get install -y unzip g{it,cc,++} {c,}make {zlib1g,lib{sqlite3,curl4-openssl,luajit-5.1,leveldb,pq}}-dev&& \
cd $(mktemp -dp /var/tmp)&&wget downloads.sourceforge.net/irrlicht/irrlicht-1.8.4.zip -O irr.zip&& \
unzip -q irr.zip&&git clone -b $branch https://github.com/minetest/minetest&&cd minetest&& \
git clone -b $branch {https://github.com/minetest,games}/minetest_game&& \
cmake . -D{BUILD_CLIENT=0,{BUILD_SERVER,RUN_IN_PLACE,ENABLE_POSTGRESQL,ENABLE_CURSES}=1,\
IRRLICHT_INCLUDE_DIR=$PWD/../irrlicht-1.8.4/include,POSTGRESQL_INCLUDE_DIR=/usr/include/postgresql/,\
POSTGRESQL_LIBRARY=/usr/lib/x86_64-linux-gnu/libpq.so.5.13,PostgreSQL_TYPE_INCLUDE_DIR=/usr/include/postgresql/}&& \
make -j$(nproc) package&&p=$(echo minetest-*.tar.gz)&&cp "$p" ~&& \
printf '\n\n\e[1;32mBuild successful, an archive called "%s" was placed in your home folder.\nTo run the server, extract the archive\
and run the executable inside the 'bin/' folder\e[0m\n' "$p")||printf '\n\n\e[1;31mBuild failed, review log output above to identify and fix the issue.\e[0m\n

Die Zertifikate für das Backend wurden mit folgendem Kommando erstellt:

sudo certbot –apache -d minetest.lmz-bw.de

Output:

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

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.

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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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
Donating to EFF: https://eff.org/donate-le

Diese Zertifikat wurden mit folgenden Anweisungen für Keycloak verwendet (eventuell direkt Pfad anpassen):

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

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 http://minetest.lmz-bw.de/ -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/%%

Die Anwendung greift auf Daten aus vier Quellen zu.

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:

UPDATE pg_database SET datistemplate = true where datname = 'minetest_template1';

UPDATE pg_database SET datallowconn = false where datname = 'minetest_template1';

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.