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 24.x (die genaue Version ist in der Datei .nvmrc festgelegt und kann mit nvm use ausgewählt werden)
• npm: Wird mit Node.js installiert
• MySQL: Version 8.x (Für die Datenbank)
• Redis: Für die Verarbeitung von Hintergrundprozessen (z. B. Synchronisation mit dem Testcenter)

Falls Docker verwendet wird, sind keine zusätzlichen Installationen von Node.js, npm, MySQL oder Redis 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:

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 (siehe Authentifizierung und Konfiguration). Eine Übersicht über die wichtigsten Umgebungsvariablen findet sich in Abschnitt 4.

2. Docker-Container starten

Die Docker-Container mit Docker Compose starten:

docker compose up -d

Dabei werden die folgenden Container gestartet:

• frontend: Vite-Entwicklungsserver für das Frontend
• backend: NestJS-Backend
• db: MySQL-Datenbank
• redis: Redis für die Verarbeitung von Hintergrundprozessen
• phpmyadmin: Weboberfläche zur Verwaltung der Datenbank (http://localhost:8082)
• coding-service: Microservice zur automatischen Kodierung von Antworten

3. Datenbank-Migrationen ausführen

Migrationen im Backend-Container ausführen:

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:

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

Außerdem muss ein Redis-Server lokal installiert und gestartet werden.

3. Abhängigkeiten installieren

Die benötigte Node.js-Version auswählen und alle benötigten Abhängigkeiten im Root-Verzeichnis des Projekts installieren:

nvm use
npm ci

4. Common-Paket bauen

Das common-Paket enthält Code, der sowohl im Frontend als auch im Backend verwendet wird. Es wird sowohl als CommonJS-Modul (für das Backend) als auch als ES-Modul (für das Frontend) gebaut. Im Root-Verzeichnis des Projekts ausführen:

npm run build -w common

Wenn sich Code im common-Paket ändert, muss es neu gebaut werden, bevor die Änderungen im Backend und Frontend verfügbar sind.

5. Backend konfigurieren

Die Beispiel .env-Datei kopieren und anpassen:

cp backend/env.sample backend/.env

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

6. Datenbank-Migrationen ausführen

Die Migrationen werden aus dem gebauten Backend-Code ausgeführt. Daher muss das Backend zunächst gebaut werden:

npm run build -w backend
npm run migration:run -w backend

7. Backend starten

Den Backend-Server im Entwicklungsmodus starten:

npm run start:dev -w backend

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

8. Frontend konfigurieren

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

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:

npm run dev -w frontend

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:

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

2. Datenbank-Migrationen anwenden

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

Der Server ist anschließend auf Port 3000 erreichbar.

Im Produktionsbetrieb liefert das Backend auch das gebaute Frontend unter dem Pfad /frontend aus. Die URLs, unter denen Backend und Frontend erreichbar sind, werden beim Bauen des Docker-Images über die Variablen VITE_API_BASEURL, VITE_LOGIN_URL und VITE_URL_QR festgelegt.

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:

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

Um als Schulaufsicht die Anmeldungsansicht einer bestimmten Schule aufzurufen, können der Anmeldungs-Webkomponente zusätzlich die Attribute is-admin und admin-school-id übergeben werden.

Alternativ können die Anmeldungs- und Admin-Views als eigenständige Seiten, z. B. in einem iframe, eingebunden werden. Diese sind unter /frontend/registration.html und /frontend/admin.html zu finden. Der API-Token wird dabei über den URL-Parameter apiToken übergeben, z. B. /frontend/admin.html?apiToken=API_TOKEN_FÜR_ADMIN.

Die Codelisten und die Rückmeldungen werden aus der Anmeldungsansicht heraus unter /frontend/codecards.html und /frontend/feedback.html geöffnet. Eine dem Testcenter vorgeschaltete Loginseite für Schüler*innen ist unter /frontend/login.html zu finden.

4. Konfiguration

Die wichtigsten Umgebungsvariablen in der .env-Datei sind:

Variable	Beschreibung
TESTCENTER_BASEURL, TESTCENTER_USERNAME, TESTCENTER_PASSWORD	URL und Zugangsdaten der Testcenter-Instanz
TESTCENTER_WORKSPACE_ID	ID des Testcenter-Workspaces, in dem alle Tests verwaltet werden
AUTOCODER_BASEURL	URL des Microservices zur automatischen Kodierung von Antworten
DATABASE_HOST, DATABASE_PORT, DATABASE_NAME, DATABASE_USER, DATABASE_PASSWORD	Verbindungsdaten der MySQL-Datenbank
DATABASE_PREFIX	Präfix für die Tabellennamen in der Datenbank
REDIS_HOSTNAME, REDIS_PORT	Verbindungsdaten des Redis-Servers
JWT_SECRET	Geheimnis zum Signieren der JWT-Tokens. Muss im Produktionsbetrieb auf eine zufällige Zeichenkette gesetzt werden
KT_AUTH_URL, KT_HOSTNAME	Authentifizierungsschnittstelle des KT-Schulportals
DUMMY_AUTH_SERVICE, DUMMY_SCHOOL_ID	Dummy-Authentifizierung (siehe Authentifizierung und Konfiguration)
VITE_API_BASEURL	URL, unter der das Frontend das Backend erreicht
VITE_LOGIN_URL, VITE_URL_QR	URLs zum Testcenter-Login, die auf den Codelisten ausgegeben werden
REGISTRATION_ORIGIN	Origin der Seite, in die die Anmeldungs-Webkomponente eingebunden ist

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 im Administrationsbereich einen zuvor exportierten Testtyp importieren. Dabei werden die Subtests, Feedback-Gruppen, Materialien und Detailhinweise des Testtyps in die Datenbank übernommen.

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:

docker compose logs