Entwicklung & Betrieb

Setup, Deployment und Betrieb

Kurzer Pfad vom Klonen des Repositories bis zum laufenden Stack – lokal via Docker Compose oder in Produktion mit Multi-Stage-Images.

Voraussetzungen

Entwicklung

Node.js >= 22
npm >= 10
Docker >= 24 + Docker Compose >= 2.20
Tesseract OCR mit deutschem Sprachpaket
MuPDF Tools

PostgreSQL und Qdrant werden über Docker Compose bereitgestellt – eine lokale Installation ist nicht nötig.

Systemabhängigkeiten installieren

bash

# Debian / Ubuntu
apt install tesseract-ocr tesseract-ocr-deu mupdf-tools ffmpeg

# macOS (Homebrew)
brew install tesseract tesseract-lang mupdf ffmpeg

Produktionsbetrieb

Docker >= 24 und Docker Compose >= 2.20
Zugang zu einer Moodle-Instanz (ab 4.x) mit aktivierter REST-API

Installation & Setup

bash

git clone https://gitlab.opencode.de/sh/digitalhub-sh/landesprogramm-offene-innovationen/daz-pilot.git
cd daz-pilot

npm install

cp .env.example .env
cp backend/.env.example backend/.env

npm install installiert dank postinstall automatisch auch die Abhängigkeiten von app/ und backend/. Für den Super-Admin-API-Key eignet sich openssl rand -hex 48.

Umgebungsvariablen

Server

Variable	Beschreibung	Beispiel
`ENVIRONMENT`	Anwendungsumgebung	development · testing · production
`NETWORK_INTERFACE`	Netzwerk-Interface	0.0.0.0
`PORT`	Server-Port	4000
`CORE_BACKEND_DOMAIN`	Backend-Domain	http://localhost:4000
`FRONTEND_DOMAIN`	Frontend-Domain (CORS)	http://localhost:3000
`SEND_SERVER_ERROR_MESSAGE`	Server-Fehler an Client senden	true · false

Datenbank (PostgreSQL)

Variable	Beschreibung	Default
`DB_HOST`	Datenbank-Host	localhost
`DB_PORT`	Datenbank-Port	5432
`DB_USER`	Datenbank-Benutzer	–
`DB_PASS`	Datenbank-Passwort	–
`DB_NAME`	Datenbank-Name	–
`DB_POOL_SIZE`	Pool-Größe	10
`DB_DEBUG_SLOW_DB_ACCESS`	Slow-Query-Logging (ms, 0 = aus)	0
`DB_MAX_DEADLOCKS`	Max. Deadlock-Retries	100

Qdrant, ML-Service, Medien

Variable	Beschreibung	Default
`QDRANT_HOST`	Qdrant-Host	localhost
`QDRANT_PORT`	Qdrant-Port	6333
`ML_SERVICE_URL`	Basis-URL des Python-Sidecars	–
`ML_SERVICE_TIMEOUT_MS`	Axios-Timeout für ML-Calls (ms)	120000
`MEDIA_STORAGE_DIR`	Verzeichnis für Bilder und temporäre Videos	./media
`MEDIA_PUBLIC_PATH`	URL-Präfix für statisches Ausliefern	/media
`FRAME_EXTRACTION_FPS`	ffmpeg-Sampling-Rate für Frame-Extraktion	2
`FRAME_EXTRACTION_CANDIDATES_PER_FRAME`	Kandidaten pro behaltenem Frame	3

Authentifizierung

Variable	Beschreibung	Hinweis
`SUPER_ADMIN_API_KEY`	API-Schlüssel für Super-Admin-Zugriff	Mindestens 64 Zeichen

Stack starten (Docker)

Option A – Alles in Docker (empfohlen für Deployment)

bash

docker compose up --build

Startet PostgreSQL, Qdrant, ML-Service, DB-Migration, Backend, Worker und Dashboard. Das Dashboard läuft auf http://localhost:3000, das Backend auf http://localhost:4000. Für den Browser muss FRONTEND_DOMAIN auf http://localhost:3000 gesetzt sein.

Option B – Nur Infra in Docker, Backend nativ

bash

docker compose up postgres qdrant ml-service -d

# im backend/-Verzeichnis:
npm run database:migrate
npm run dev:core_backend   # Hot-Reload (eigenes Terminal)
npm run dev:worker

Für Option B braucht es eine lokale docker-compose.override.yml (gitignored), die Postgres auf Port 5433 und den ML-Service auf 8000 exponiert. In backend/.env dann DB_HOST=localhost und DB_PORT=5433.

Erster Start des ML-Service

Beim ersten Start lädt der ML-Service ~2 GB SigLIP-Gewichte herunter und ist bis zu ~5 Minuten unhealthy. Status prüfen mit docker compose ps.

Mobile App und Dashboard nativ

bash

# Mobile App (aus app/)
npm start

# Dashboard (aus dashboard/)
npm run dev

Das Backend ist unter http://localhost:4000 erreichbar, die Swagger-UI unter http://localhost:4000/api/v1/swagger.

Datenbank & Migrationen

bash

npm run database:create   # Datenbank erstellen
npm run database:migrate  # Migrationen ausführen
npm run database:drop     # Datenbank löschen
npm run database:clean    # drop → create → migrate

Der PoolController bietet drei Zugriffsmodi: nicht-transaktionale Einzelabfragen (fakeDatabaseTransaction), Read-Only (beginRead) und Read-Write mit Deadlock-Erkennung (beginWrite).

Deployment

Produktionsbetrieb (Docker)

bash

git clone https://gitlab.opencode.de/sh/digitalhub-sh/landesprogramm-offene-innovationen/daz-pilot.git
cd daz-pilot

cp .env.example .env   # und anpassen

docker compose up --build -d

API, Worker und DB-Migrator teilen sich ein Image (backend/Dockerfile); die Migration läuft als einmaliger Job vor dem Backend-Start. Für Produktion empfiehlt sich ein Reverse-Proxy vor backend und dashboard(z. B. Traefik via Coolify).

Einzelnes Backend-Image bauen

bash

docker build -t daz-pilot-backend backend/

Mobile Apps

iOS: App Store
Android: Google Play Store

Scripts-Referenz

Script	Beschreibung
`dev:core_backend`	Entwicklungsserver mit Hot-Reload (tsx watch)
`start:core_backend`	Gebautes Backend starten
`start:database_migrator`	Migrationen ausführen
`start:qdrant`	Qdrant-Container starten
`build`	Alle Workspaces bauen
`build:clean`	Build-Artefakte entfernen
`test`	Tests ausführen (node --test)
`database:create`	PostgreSQL-Datenbank erstellen
`database:migrate`	Migrationen ausführen
`database:drop`	Datenbank löschen
`database:clean`	Datenbank komplett zurücksetzen
`script:create_openapi_file`	OpenAPI-Spezifikation generieren
`format`	Code formatieren (Prettier)
`lint`	Linting durchführen (ESLint)
`pretty_log`	Pino-Logs formatiert ausgeben

Tests

bash

cd backend && npm test

Automatisierte Unit-Tests (Backend & Frontend)
Integrationstests
End-to-End-Tests
Wiederholte Nutzertests in Berufsschulklassen

Branch-Strategie

text

main  ──►  development  ──►  production

main – aktueller Entwicklungsstand
development – Integrationsumgebung
production – stable Release

Feature-Branches werden von main abgezweigt und per Merge Request zusammengeführt.

ML-Smoke-Test

Das Repository liefert ein Shell-Skript, das die komplette ML-Pipeline (embed → dedup → train → load → classify + OOD-Detection) gegen den laufenden Stack testet:

bash

docker compose -f infra/docker-compose.yml up qdrant ml-service
./scripts/ml_service_smoke_test.sh