TBA II Dokumentation

Erscheinungsbild

Installation ​

1. Voraussetzungen ​

Falls das Projekt ohne Docker lokal ausgeführt wird, stellen Sie sicher, dass folgende Software und Tools auf Ihrem System installiert sind:

  • Node.js: Version >= 20.x (Aktuelle LTS-Version empfohlen)
  • npm: Wird mit Node.js installiert
  • MySQL: Version 8.x (Für die Datenbank)

Falls Docker verwendet wird, sind keine zusätzlichen Installationen von Node.js, npm oder MySQL erforderlich. Es wird lediglich benötigt:

  • Docker: Version >= 20.x
  • Docker Compose

Die Nutzung von Docker wird empfohlen.

2. Entwicklungsumgebung ​

2.1 Installation mit Docker ​

Falls die Anwendung in Docker-Containern ausgeführt werden soll, können die folgenden Schritte ausgeführt werden:

1. .env-Datei anpassen ​

Die .env-Beispieldatei ins Root-Verzeichnis des Projekts kopieren und anpassen:

bash
cp env.sample .env

Wenn nicht das Schulportal von kompetenztest.de als Authentifizierungsbackend verwendet wird, muss die Variable DUMMY_AUTH_SERVICE auf true gesetzt werden, damit ein Dummy-Authentifizierungsservice für Demozwecke verwendet wird.

2. Docker-Container starten ​

Die Docker-Container mit Docker Compose starten:

bash
docker compose up -d

3. Datenbank-Migrationen ausführen ​

Migrationen im Backend-Container ausführen:

bash
docker compose exec backend npm run migration:run

4. Backend-API-Dokumentation ​

Die Swagger-API-Dokumentation ist über http://localhost:3000/api zugänglich.

5. Frontend im Docker starten ​

Das Frontend ist unter http://localhost:5173/admin und http://localhost:5173/registration verfügbar.

2.2 Installation ohne Docker ​

1. Code herunterladen ​

Zunächst muss der Code des Projekts auf den lokalen Rechner heruntergeladen werden. Dies kann mit Git erfolgen:

bash
# Klonen des Repositories
git clone https://git.uni-jena.de/inio/tba2/bkt.git
cd bkt

2. Datenbank-Setup ​

MariaDB/MySQL lokal installieren und starten. Nach dem Start des MySQL-Servers eine neue Datenbank für das Projekt anlegen.

3. Abhängigkeiten installieren ​

Alle benötigten Abhängigkeiten im Root-Verzeichnis des Projekts installieren:

bash
npm install

4. Common-Paket bauen ​

Das common-Paket enthält Code, der sowohl im Frontend als auch im Backend verwendet wird. In das common-Verzeichnis wechseln und bauen:

bash
cd common
./build.sh

5. Backend konfigurieren ​

Die Beispiel .env-Datei kopieren und anpassen:

bash
cp backend/env.sample backend/.env

Die .env-Datei mit den spezifischen Konfigurationen (Datenbank, Authentifizierung, etc.) bearbeiten.

6. Datenbank-Migrationen ausführen ​

Migrationen ausführen:

bash
npm run migration:run

7. Backend starten ​

Den Backend-Server im Entwicklungsmodus starten:

bash
npm run start:dev

Der Backend-Server läuft nun auf http://localhost:3000.

8. Frontend konfigurieren ​

Die Beispiel .env-Dateien für das Frontend kopieren:

bash
cp frontend/env.production.sample frontend/.env.production
cp frontend/env.development.sample frontend/.env.development

Die .env-Dateien für die Entwicklung bearbeiten.

9. Frontend starten ​

Den Frontend-Server starten:

bash
cd frontend
npm run dev

Der Frontend-Server läuft nun auf dem angezeigten Port (z.B. http://localhost:5173).

3. Produktionseinsatz ​

3.1 Production Server ​

1. Production Server starten ​

Zunächst die .env-Datei für den Produktionseinsatz anpassen. Dann Anwendungs- und Datenbankcontainer starten:

bash
docker compose -f compose.prod.yml up -d

2. Datenbank-Migrationen anwenden ​

bash
docker compose -f compose.prod.yml exec backend npm run migration:run

Der Server ist anschließend auf Port 3000 erreichbar.

3.2 Frontend in ein bestehendes System einbinden ​

Die Anmeldungs- und Admin-Views können als Web-Komponenten in andere Webseiten eingebunden werden.

Die für die Anmeldungs-Webkomponente notwendige Javascript Datei wird unter /frontend/assets/registration.js ausgeliefert. Die Administrations-Webkomponente unter /frontend/assets/admin.js.

Beispiel:

html
<!DOCTYPE html>
<html>
    <head>
        <!-- ... -->
    </head>
    <body>
        <!-- Für Anmeldung: -->
        <bkt-registration-widget api-token="API TOKEN FÜR SCHULE"></bkt-registration-widget>
        <script type="module" src="URL ZU registration.js"></script>

        <!-- Für Admin: -->
        <bkt-admin-widget api-token="API TOKEN FÜR ADMIN"></bkt-admin-widget>
        <script type="module" src="URL ZU admin.js"></script>
    </body>
</html>

Eine dem Testcenter vorgeschaltete Loginseite für Schüler*innen ist unter /frontend/login.html zu finden.

4. Konfiguration ​

Um den BKT Manager nach der Installation zu konfigurieren, nutzen Sie den Administrationsbereich.

5. Import von Beispieldaten ​

Um Beispieldaten für Rückmeldungen zu laden, können Sie das SQL-Skript unter backend/sql/create-subtests-groups-materials.sql verwenden. Dieses importiert die bei der prototypischen Implementierung des Basiskompetenztest in Schleswig-Holstein im Rahmen des TBA II-Projekts verwendeten Metadaten und Förderhinweise in die Datenbank.

Um Daten für einen Testtyp zu importieren, setzen sie eine der Variablen @testTypeIdDeutschLesen, @testTypeIdDeutschOrthografie, @testTypeIdDeutschZuhören und/oder @testTypeIdMathematik auf die ID des jeweiligen Testtyps in Ihrer Datenbank.

Zum Import führen Sie den folgenden Befehl im BKT-Manager Repository-Ordner aus:

bash
cat backend/sql/create-subtests-groups-materials.sql | docker exec -i bkt-db-1 bash -c 'mysql -u $MYSQL_USER -p$MYSQL_PASSWORD $MYSQL_DATABASE'

Bei bkt-db-1 handelt es sich um den Containernamen der BKT Manager Datenbank. Dieser kann bei Ihnen unter Umständen ein anderer sein. Führen Sie docker ps | grep db aus, um den Namen zu erhalten und passen Sie gegebenenfalls den Befehl an.

6. API-Dokumentation ​

Die REST-API wird mit Swagger dokumentiert. Die API-Dokumentation kann auf dem Entwicklungsserver unter http://localhost:3000/api eingesehen werden.

7. Troubleshooting ​

Falls Probleme bei der Installation oder beim Starten auftreten, sollten die folgenden Punkte überprüft werden:

  • Fehlende Umgebungsvariablen: Alle .env-Dateien müssen korrekt konfiguriert sein.
  • Docker-Container: Falls die Docker-Container nicht starten, können die Docker-Logs überprüft werden:
bash
docker compose logs