Arbeitsplatz-Setup für KI-Assistenten

Diese Datei beschreibt, wie MPM auf einem neuen Arbeitsplatz eingerichtet und angepasst wird. Lies sie zusammen mit README.md, docs/ARCHITECTURE.md und docs/MODULE-MARKETPLACE.md, bevor du Änderungen vornimmst.

Projektziel und Architektur

MPM ist eine Management-Plattform für Benutzer, Rollen und externe Module. Das Frontend ist React/Vite/TypeScript, das Backend NestJS/TypeScript, die Plattformdaten liegen in PostgreSQL. Die Plattform wird mit Docker Compose gestartet. Installierte Module laufen in eigenen Compose-Projekten mit eigenen Containern und persistenten Volumes; MPM verwaltet deren Start, Stop, Health, Disable und Remove. Der Docker-Socket wird nur vom MPM-Backend verwendet und niemals an Modulcontainer weitergereicht.

Wichtige Verzeichnisse:

apps/platform-frontend: React-Oberfläche
apps/platform-backend: API, Authentifizierung, Marketplace und Modulverwaltung
packages/platform-module-sdk: SDK-Vertrag für Module
modules/demo: Referenzmodul
docker: Nginx- und Supervisor-Konfiguration
docs: Architektur und Modul-/Marketplace-Verträge

Änderungen an Modulinstallation oder Container-Lifecycle müssen den Compose-Stack, persistente Daten, Gateway-Netzwerk und Fehler-/Recovery-Pfade berücksichtigen. Lies dafür module-container-manager.ts, module-installer.ts, modules.service.ts sowie die Modul-Dokumentation.

Voraussetzungen

Für den üblichen Betrieb:

Git
Docker Desktop mit Linux-Containern und Docker Compose v2; unter Windows ist ein aktiviertes WSL2-Backend empfehlenswert
VS Code und ein KI-Assistent mit Zugriff auf den geöffneten Projektordner

Für lokale Frontend-/Backend-Entwicklung außerhalb von Docker zusätzlich Node.js 24 und npm. Die Module haben eigene Laufzeit- und Build-Anforderungen gemäß ihrem Manifest.

Beim ersten Öffnen auf einem neuen Arbeitsplatz

Repository auschecken und den aktuellen Arbeitsbranch verwenden. Den vorhandenen Branch nicht ungefragt auf main umbenennen oder lokale Änderungen verwerfen.
git status --short --branch prüfen. Nicht committete Änderungen gehören möglicherweise dem Nutzer; niemals resetten, stashen, überschreiben oder entfernen, ohne vorher genau zu prüfen.
Docker Desktop starten und sicherstellen, dass Linux-Container und Compose v2 funktionieren.
.env nur anlegen, wenn sie noch nicht vorhanden ist: .env.example kopieren und ausschließlich lokale Entwicklungswerte eintragen. Eine vorhandene .env nie ersetzen oder ausgeben.
Secrets dieses Arbeitsplatzes getrennt halten. Keine Passwörter, OAuth-Secrets, Zugriffstokens, Cookies oder privaten Schlüssel in Quellcode, Dokumentation, Kommandoausgaben, Commits oder Issues übernehmen. Beispielwerte in .env.example sind Platzhalter.
Bei rein lokaler HTTP-Entwicklung NODE_ENV=development und COOKIE_SECURE=false verwenden. In Produktion muss HTTPS aktiv sein und COOKIE_SECURE=true gesetzt werden.
Für OAuth-Entwicklung sind pro Provider eigene OAuth-Clientdaten mit passender Callback-URL nötig. Ohne OAuth-Konfiguration können die übrigen Plattformfunktionen lokal verwendet werden; Provider dürfen nicht mit unvollständiger Konfiguration gesetzt werden. Bei aktivem OAuth einen dauerhaften MARKETPLACE_TOKEN_ENCRYPTION_KEY mit mindestens 32 Zeichen lokal generieren und geheim halten. Für Modulkonfigurationen zusätzlich einen dauerhaften MODULE_CONFIG_ENCRYPTION_KEY mit mindestens 32 Zeichen generieren und geheim halten. Ohne diesen Schlüssel lassen sich gespeicherte Modul-Secrets nicht entschlüsseln; bei Schlüsselverlust oder Rotation müssen die Modulkonfigurationen erneuert werden.
APP_PORT bei Bedarf anpassen, falls 8080 belegt ist. MARKETPLACE_PUBLIC_URL muss die vom Browser erreichbare Basisadresse samt Port enthalten, etwa http://127.0.0.1:8080. Diese Adresse auch zum Öffnen der Plattform verwenden. Moduloberflächen nutzen einen eigenen Host: lokal automatisch den jeweils anderen Loopback-Namen (localhost oder 127.0.0.1), bei öffentlichen Domains standardmäßig modules.<Plattformhost>. Für einen anderen Host MODULE_PUBLIC_ORIGIN setzen; in Produktion DNS und HTTPS für beide Hosts einrichten.
DOCKER_SOCKET_GID ist hostabhängig. Docker Desktop verwendet häufig 0; bei Linux ist die tatsächliche Gruppe des Docker-Sockets zu verwenden. Änderungen daran erst nach Prüfung der Docker-Berechtigungen vornehmen.

Die Datenbankverbindung innerhalb des Compose-Netzwerks verwendet den Hostnamen postgres. Bei Backend-Ausführung direkt auf dem Host muss DATABASE_URL auf 127.0.0.1:5432 zeigen. Niemals den Compose-internen Hostnamen postgres für einen Backendprozess auf dem Host verwenden.

Plattform mit Docker starten

Im Projektstamm:

docker compose up --build -d
docker compose ps

Danach die in MARKETPLACE_PUBLIC_URL konfigurierte Adresse öffnen (Beispiel: http://127.0.0.1:8080). Das initiale Admin-Konto wird beim ersten Datenbankstart aus ADMIN_USERNAME, ADMIN_EMAIL und ADMIN_PASSWORD angelegt. Spätere Änderungen dieser Variablen ändern ein bereits angelegtes Datenbankkonto nicht automatisch.

Logs und Neustart:

docker compose logs -f platform
docker compose logs -f postgres
docker compose restart platform

Für normale Neustarts oder Updates kein docker compose down -v verwenden: -v löscht persistente Datenbank- und Moduldaten.

Lokale Entwicklung ohne Plattform-Container

PostgreSQL zuerst starten:

docker compose up -d postgres

Dann in separaten Terminals:

Set-Location apps/platform-backend
npm ci
npm run start:dev

Set-Location apps/platform-frontend
npm ci
npm run dev

Der Backendprozess benötigt gültige Variablen aus .env; beim lokalen Start muss DATABASE_URL auf 127.0.0.1 zeigen. Falls die Entwicklungsumgebung .env nicht automatisch lädt, Variablen sicher über die lokale Shell/VS-Code-Konfiguration einlesen; keine Secrets in Startskripte committieren.

Arbeitsregeln für Änderungen

Vor Änderungen relevante AGENTS.md-Dateien, Dokumentation und betroffene Implementierungen lesen.
Vor jedem Commit Status und Diff prüfen. Nur die beabsichtigten Dateien aufnehmen; Nutzeränderungen nicht stillschweigend verwerfen.
Keine echten Zugangsdaten in Ausgaben oder Dokumentation schreiben. Wenn ein Secret versehentlich in einen Commit gelangt ist, es als kompromittiert behandeln und rotieren; bloßes Löschen aus der aktuellen Datei reicht nicht.
API-Änderungen auf DTO/Validierung, Authentifizierung, RBAC, CSRF, Audit und Frontend-Verwendung prüfen.
Containeränderungen auf Windows/Docker Desktop und Linux, Restart/Stop/Remove, Netzwerk-Neuerstellung, Datenpersistenz und Logs prüfen.
Datenbankänderungen als neue Migration ergänzen; bestehende Migrationen nicht nachträglich umschreiben, wenn sie schon angewendet sein könnten.
UI-Änderungen an bestehenden Komponenten und Dark-/Light-Theme-Konventionen ausrichten.
Abhängigkeiten nur bei Bedarf ändern und Lockfiles konsistent halten.
Nach Codeänderungen, die den lokalen Plattformcontainer betreffen, diesen neu bauen und starten, damit der Container die aktuellen Änderungen erhält. Tests, externe Deployments, Commits und Pushes nur ausführen, wenn der Nutzer sie angefordert hat. Wenn er Verifikation verlangt, die tatsächlich ausgeführten Befehle und Ergebnisse angeben.
Bei einem gewünschten Push Ziel-Remote und Branch verifizieren, den kompletten Commit-Diff auf Secrets prüfen und keine Force-Pushes ausführen, außer der Nutzer weist sie ausdrücklich an.

Häufige Arbeitsplatzprobleme

Port belegt: APP_PORT in .env ändern und MARKETPLACE_PUBLIC_URL synchron anpassen. PostgreSQL-Port 5432 kann für reine Compose-Nutzung bei Bedarf ebenfalls hostseitig angepasst werden; dann muss die lokale DATABASE_URL mitziehen.
Backend startet nicht: Prüfen, ob alle Pflichtvariablen gesetzt sind, ADMIN_PASSWORD mindestens 10 Zeichen hat, DATABASE_URL den richtigen Host verwendet und PostgreSQL gesund ist.
OAuth-Callback schlägt fehl: Externe Callback-URL muss exakt zur Provider-Konfiguration passen, inklusive Schema, Host, Port und Pfad /api/v1/marketplace/oauth/<provider>/callback. Redirect-URL und MARKETPLACE_PUBLIC_URL müssen übereinstimmen.
Modulcontainer lassen sich nicht steuern: Docker Desktop muss laufen; Socket-Mount und DOCKER_SOCKET_GID prüfen. Docker-Socket-Zugriff ist privilegiert; keine Erhöhung für Modulcontainer aktivieren.
Modul kann nach Stop nicht starten: MPM-Logs und den Modul-Compose-Stack prüfen; Containerstatus, Gateway-Netz und Volume-Status erfassen. Nicht als Erstes Datenvolumes löschen.
Windows-Dateirechte oder Pfade: Docker Compose läuft in Linux-Containern; Datei- und Socketpfade aus Docker Desktop/WSL berücksichtigen und möglichst nicht zwischen Windows- und WSL-Dateisystemen hin- und herkopieren.

Dokumente zum Modulvertrag

Vor Implementierung oder Anpassung eines Marketplace-Moduls außerdem docs/MODULE-MARKETPLACE.md, modules/README.md und packages/platform-module-sdk/README.md lesen. Das Modulmanifest und dessen Compose-/Health-/Datenvolume-Angaben sind Teil der Integrationsschnittstelle.

9.2 KiB Raw Permalink Blame History