115 lines
8.8 KiB
Markdown
115 lines
8.8 KiB
Markdown
# 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
|
|
|
|
1. Repository auschecken und den aktuellen Arbeitsbranch verwenden. Den vorhandenen Branch nicht ungefragt auf `main` umbenennen oder lokale Änderungen verwerfen.
|
|
2. `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.
|
|
3. Docker Desktop starten und sicherstellen, dass Linux-Container und Compose v2 funktionieren.
|
|
4. `.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.
|
|
5. 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.
|
|
6. 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.
|
|
7. 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.
|
|
8. `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`.
|
|
9. `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:
|
|
|
|
```powershell
|
|
docker compose up --build -d
|
|
docker compose ps
|
|
```
|
|
|
|
Danach die in `APP_PORT` konfigurierte Adresse öffnen (Standard `http://localhost: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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
docker compose up -d postgres
|
|
```
|
|
|
|
Dann in separaten Terminals:
|
|
|
|
```powershell
|
|
Set-Location apps/platform-backend
|
|
npm ci
|
|
npm run start:dev
|
|
```
|
|
|
|
```powershell
|
|
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.
|