From 331f3bed40909b11d7982d5456037246cc98e90d Mon Sep 17 00:00:00 2001 From: Stefan Mogeritsch Date: Thu, 5 Mar 2026 10:24:25 +0100 Subject: [PATCH] docs: add comprehensive Zora system architecture documentation Introduced `Zora_System_Architektur.md` outlining the ARM64-based system design for "Zora." Covers Gitea setup, CI/CD workflows, deployment methods, service configurations, and developer guidelines. --- docs/️Zora_System_Architektur.md | 75 +++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/️Zora_System_Architektur.md diff --git a/docs/️Zora_System_Architektur.md b/docs/️Zora_System_Architektur.md new file mode 100644 index 00000000..6411627c --- /dev/null +++ b/docs/️Zora_System_Architektur.md @@ -0,0 +1,75 @@ + +## 🏗️ System-Architektur "Zora" (ARM64) + +**Stand: 05. März 2026** + +Die gesamte Umgebung läuft auf einer **ARM64-Architektur** (Cortex-A720). Dies bietet hohe Performance bei geringem Energieverbrauch, erfordert aber spezifische Build-Konfigurationen (SVE-Support, ARM64-Images). + +### 1. Gitea & Central Registry (LXC) + +* **Rolle:** Quellcode-Verwaltung, CI/CD-Steuerung und Container-Registry. +* **IP-Adresse:** `10.0.0.22:3000` (Intern) / `git.mo-code.at` (Extern). +* **Registry:** Integriert unter `git.mo-code.at`. +* **Pfad-Struktur:** `git.mo-code.at/mocode-software/meldestelle/` + + +* **Wichtig für Entwickler:** Authentifizierung erfolgt via Gitea-Benutzer oder Access-Token. + +### 2. Gitea-Power-Runner (VM 102) + +Der Runner ist das "Arbeitstier" des Systems. + +* **Software:** `act_runner` (v0.2.11). +* **Ressourcen:** 16 GiB RAM (optimiert für schwere Kotlin/JS-Builds). +* **Build-Stack:** Java 25 (Temurin), Gradle 9.3.1. +* **Besonderheiten:** +* **Sequenzieller Build:** Um GitHub Rate-Limits und RAM-Spitzen zu vermeiden, arbeitet der Runner die Matrix-Jobs kontrolliert ab. +* **Docker Buildx:** Native ARM64-Builds mit Optimierungs-Flags (`-XX:+UseTransparentHugePages`, `-XX:+UseSVE=1`). +* **Der "Terser-Fix":** Für die Web-App wurde die Minifizierung deaktiviert, da das Terser-Plugin mit der `sqlite-wasm` Bibliothek kollidiert. Dies wird über die Datei `z_disable-minification.js` im Webpack-Ordner sichergestellt (das Präfix `z_` erzwingt die Ausführung als letzten Schritt). + + + +### 3. Meldestelle-Host (VM 110 / .50) + +Die Zielumgebung für das Deployment. + +* **Deployment-Methode:** Docker Compose mit Profilen (`infra`, `backend`, `gui`). +* **Verzeichnis:** `~/meldestelle/` +* **Service-Übersicht:** + +| Dienst | Externer Port | Interner Port | Image-Name (Registry) | +| --- | --- | --- | --- | +| **Web-App** | 4000 | 4000 (Caddy) | `web-app` | +| **API-Gateway** | 8081 | 8081 | `api-gateway` | +| **Keycloak** | 8180 (Admin) | 8080 | `keycloak` | +| **Ping-Service** | 8082 | 8082 | `ping-service` | +| **Consul** | 8500 | 8500 | `hashicorp/consul` | + +--- + +## 🛠️ Der CI/CD Workflow + +Wenn ein Entwickler Code in den `main`-Branch pusht: + +1. **Trigger:** Gitea Actions erkennt den Push. +2. **Build:** Der Runner (VM 102) baut die Services. +* Das Frontend nutzt Kotlin/JS. +* Das Backend nutzt Kotlin/JVM (Java 25). + + +3. **Tagging:** Jedes Image erhält zwei Tags: +* `:latest` (für den schnellen Pull). +* `:sha-` (für eindeutige Versionierung und Rollbacks). + + +4. **Registry:** Die Images werden nach `git.mo-code.at` gepusht. +5. **Deployment (Manuell/Host):** Auf der VM 110 wird via `docker compose pull` die neueste Version geladen. + +--- + +## 📝 Wichtige Hinweise für Entwickler + +* **Frontend-Builds:** Lokal kann weiterhin mit `./gradlew jsBrowserDistribution` gearbeitet werden. Im Production-Build (`-Pproduction=true`) sorgt die Konfiguration im Ordner `webpack.config.d` dafür, dass der Runner nicht abstürzt. +* **Docker-Registry:** Vor dem ersten Pull auf einem neuen System ist ein `docker login git.mo-code.at` zwingend erforderlich. +* **Service-Discovery:** Die Dienste kommunizieren intern über das Docker-Netzwerk `meldestelle-network`. Namen wie `api-gateway`, `keycloak` oder `postgres` werden automatisch aufgelöst. +