docs: massive restructuring of documentation, development guides and agent playbooks
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
---
|
||||
type: Report
|
||||
status: ARCHIVED
|
||||
owner: Frontend Expert
|
||||
---
|
||||
# 🧹 Troubleshooting Log: Frontend Docker Build & Runtime Config
|
||||
|
||||
**Datum:** 02.02.2026
|
||||
**Status:** ⚠️ BLOCKED (Build Failure)
|
||||
**Thema:** Dockerisierung des KMP Frontends (JS/IR) mit Caddy und Runtime-Konfiguration.
|
||||
|
||||
## 1. Zielsetzung
|
||||
Stabilisierung des Frontend-Deployments via Docker Compose.
|
||||
* **Architektur:** Single Page Application (SPA) served by Caddy.
|
||||
* **Anforderung:** "Build Once, Deploy Anywhere" -> Konfiguration (API URL) muss zur Laufzeit (Runtime) injiziert werden, nicht zur Build-Zeit.
|
||||
* **Tech Stack:** Kotlin 2.3.0, Gradle 9.2.1, Compose Multiplatform 1.10.0.
|
||||
|
||||
## 2. Implementierte Lösung (Code-Ebene)
|
||||
Die Architektur für die Runtime-Konfiguration wurde erfolgreich implementiert:
|
||||
|
||||
1. **Kotlin (`Config.kt`, `main.kt`):**
|
||||
* Die App lädt vor dem Start der UI eine `config.json` via `window.fetch`.
|
||||
* `AppConfig` wird in Koin registriert.
|
||||
2. **Caddy (`Caddyfile`, `config.json`):**
|
||||
* Caddy Webserver ersetzt Nginx.
|
||||
* Nutzt das `templates` Modul, um Environment-Variablen (`API_BASE_URL`) in die `config.json` zu rendern.
|
||||
3. **Dockerfile:**
|
||||
* Multi-Stage Build (Gradle -> Caddy).
|
||||
* Optimiertes Caching für Gradle 9.x.
|
||||
|
||||
## 3. Das Problem: Gradle Build Fehler
|
||||
Der Build schlägt im Docker-Container (und teilweise lokal) fehl mit:
|
||||
`PluginApplicationException: Failed to apply plugin class 'org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin'.`
|
||||
`The Kotlin Gradle plugin was loaded multiple times in different subprojects...`
|
||||
|
||||
### Ursache
|
||||
In einem Multi-Modul KMP-Projekt (Shell + Core Libraries) versuchen mehrere Module, die JavaScript-Umgebung (Node.js/Browser) zu konfigurieren.
|
||||
* **Shell (`meldestelle-portal`):** Benötigt `browser()` für Webpack/Distribution.
|
||||
* **Libraries (`core/*`):** Benötigen JS-Target für Kompilierung, nutzen teilweise `npm()` Abhängigkeiten (z.B. `local-db` für SQLite).
|
||||
* **Konflikt:** Gradle 9.x und das Kotlin-Plugin geraten in einen Race-Condition-Zustand, wenn das `NodeJsRootPlugin` transitiv mehrfach initialisiert wird.
|
||||
|
||||
## 4. Durchgeführte Versuche
|
||||
|
||||
| Versuch | Änderung | Ergebnis | Analyse |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Basis** | `alias(libs.plugins...)` in allen Modulen. `browser {}` in allen Modulen. | ❌ FAILED | "Plugin loaded multiple times". |
|
||||
| **2. Library Mode** | Entfernen von `browser {}` aus allen Core-Modulen. Nur `binaries.library()`. | ⚠️ SUCCESS (Lokal) / ❌ FAILED (Docker) | Lokal: Warnung "JS Environment Not Selected". Docker: Trotzdem Fehler, vermutlich wegen `npm()` Dependency in `local-db`. |
|
||||
| **3. Explicit Browser** | Hinzufügen von minimalem `browser { testTask { enabled = false } }` in Libraries. | ❌ FAILED | Sofortiger "Plugin loaded multiple times" Fehler. |
|
||||
| **4. Plugin ID** | Nutzung von `id("org.jetbrains.kotlin.multiplatform")` statt `alias`. | ❌ FAILED | "Plugin not found" (Version Resolution via Catalog schlägt fehl). |
|
||||
| **5. Revert** | Zurück zu "Library Mode" (Versuch 2). | ❌ FAILED | Der Fehler bleibt hartnäckig im Docker-Build bestehen. |
|
||||
|
||||
## 5. Nächste Schritte (Planung)
|
||||
Das Problem liegt in der Gradle-Konfiguration der JS-Targets im Monorepo.
|
||||
|
||||
1. **Root-Level Node.js Konfiguration:** Das `NodeJsRootPlugin` muss zwingend **einmalig** im Root-Projekt konfiguriert werden, um den Konflikt in den Submodulen zu lösen.
|
||||
2. **Convention Plugin:** Erstellung eines `buildSrc` oder `conventions` Plugins, das die JS-Konfiguration zentralisiert (`apply(plugin = "kotlin-multiplatform")`).
|
||||
3. **Workaround:** Explizites `rootProject.plugins.apply(...)` für das NodeJs-Plugin in der Root `build.gradle.kts`.
|
||||
|
||||
---
|
||||
*Dokumentiert durch Curator Agent.*
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
type: Report
|
||||
status: ARCHIVED
|
||||
owner: Frontend Expert
|
||||
---
|
||||
# 🧹 Troubleshooting Log: Gradle 9.x & KMP Docker Build (Part 2)
|
||||
|
||||
**Datum:** 02.02.2026
|
||||
**Status:** ⚠️ BLOCKED (Docker Build Failure) / ✅ SUCCESS (Local Build)
|
||||
**Thema:** `IsolatedKotlinClasspathClassCastException` im Docker-Build mit Gradle 9.3.1.
|
||||
|
||||
## 1. Zusammenfassung
|
||||
Wir haben versucht, den Frontend-Build im Docker-Container zu stabilisieren. Lokal läuft der Build (`./gradlew build`) erfolgreich durch, inklusive WASM-Support und Runtime-Konfiguration. Im Docker-Container scheitert der Build jedoch hartnäckig an einem Plugin-Konflikt.
|
||||
|
||||
## 2. Das Problem
|
||||
**Fehler:** `IsolatedKotlinClasspathClassCastException: The Kotlin Gradle plugin was loaded multiple times in different subprojects...`
|
||||
**Kontext:** Gradle 9.2.1 / 9.3.1, Kotlin 2.3.0, Docker (ursprünglich `--no-daemon`).
|
||||
|
||||
### Analyse
|
||||
* Der Fehler tritt auf, weil das `NodeJsRootPlugin` (transitiv via KMP) mehrfach initialisiert wird.
|
||||
* **Lokal:** Der Gradle Daemon cached Classloader, wodurch das Plugin als "dasselbe" erkannt wird.
|
||||
* **Docker:** Durch die Isolation (und vermutlich Caching-Artefakte) werden Plugin-Klassen mehrfach geladen und sind nicht cast-bar (`ClassCastException`).
|
||||
|
||||
## 3. Durchgeführte Maßnahmen & Ergebnisse
|
||||
|
||||
| Versuch | Maßnahme | Ergebnis (Docker) | Erkenntnis |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1. Root Force** | `apply<NodeJsRootPlugin>()` im Root `build.gradle.kts`. | ❌ FAILED | Timing-Problem im Docker, Plugin wird zu spät oder falsch geladen. |
|
||||
| **2. KMP Root** | `alias(...) apply true` im Root + `kotlin { jvm() }`. | ❌ FAILED | `IsolatedKotlinClasspathClassCastException` bleibt. |
|
||||
| **3. Central Mgmt** | `pluginManagement` in `settings.gradle.kts` + `id("...")` ohne Version in Subprojekten. | ❌ FAILED | Architektonisch sauberster Weg, aber löst das Classloader-Problem im Docker nicht. |
|
||||
| **4. Daemon** | Entfernen von `--no-daemon` im Dockerfile. | ❌ FAILED | Daemon startet, aber der Fehler tritt trotzdem auf. |
|
||||
| **5. Upgrade** | Upgrade auf Gradle 9.3.1. | ❌ FAILED | Fehler persistiert auch in der neuesten Version. |
|
||||
| **6. Property** | `kotlin.mpp.allowMultiplePluginDeclarations=true`. | ❌ FAILED | Scheint in Gradle 9.x / KMP 2.3.0 wirkungslos zu sein. |
|
||||
|
||||
## 4. Status Quo
|
||||
* **Lokal:** ✅ Build & Run funktionieren perfekt.
|
||||
* **Docker:** ❌ Build bricht ab.
|
||||
* **Architektur:** Wir haben jetzt eine sehr saubere Gradle-Konfiguration (Zentrales Plugin-Management), die wir beibehalten sollten.
|
||||
|
||||
## 5. Nächste Schritte (Hypothesen)
|
||||
1. **Cache Corruption:** Die Docker-Layer (`--mount=type=cache`) könnten korrupte Gradle-Caches enthalten. Ein Build *ohne* Cache-Mounts muss getestet werden.
|
||||
2. **Gradle 9 Inkompatibilität:** Es ist möglich, dass KMP 2.3.0 noch nicht vollständig kompatibel mit dem strikten Classpath-Isolation-Modus von Gradle 9 ist.
|
||||
3. **Workaround:** Ein Downgrade auf Gradle 8.x wurde diskutiert, aber abgelehnt. Wir müssen einen Weg finden, Gradle 9 zu zähmen.
|
||||
|
||||
---
|
||||
*Dokumentiert durch Curator Agent.*
|
||||
Reference in New Issue
Block a user