mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: reorganize and archive documentation for improved structure

Browse Source 
Moved outdated files to the `_archive` folder and reorganized infrastructure-related documentation into the `07_Infrastructure` directory. Improved clarity and ensured logical grouping of files.
This commit is contained in:
Stefan Mogeritsch
2026-03-05 11:34:58 +01:00
parent 6c1f6a5818
commit 084eb8e999
9 changed files with 0 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/07_Infrastructure/Heim-Netzwerk-Plan_02-2026.md
+36
View File
@@ -0,0 +1,36 @@
# Heimnetzwerk
```mermaid
graph TD
%% Internet & Modem
WAN((Internet A1)) --- ONT[A1 Glasfaser ONT]
ONT ---|RJ45 - VLAN 2 / PPPoE| Router[VLAN-Router / Firewall]
subgraph Keller [Keller: Technik & Server]
Router ---|Trunk: Alle VLANs| Switch[Managed 10G Switch]
subgraph ServerZone [VLAN 20: Apps & Server]
Switch ===|10GbE Port 1| MiniPC[Mini-PC Server]
Switch ---|10GbE Port 2| MiniPC
note1[Dual 10G für Redundanz oder Bonding]
end
end
subgraph Etagen [Wohnbereich: EG & DG]
Switch ---|Cat-7| AP_EG[Access Point EG]
Switch ---|Cat-7| AP_DG[Access Point DG]
AP_EG -.-> SSID_P((WLAN Privat - VLAN 10))
AP_EG -.-> SSID_A((WLAN Apps - VLAN 20))
end
%% Definition der VLANs
classDef vlan10 fill:#e1f5fe,stroke:#01579b
classDef vlan20 fill:#fff3e0,stroke:#e65100
class MiniPC,SSID_A vlan20
class SSID_P vlan10
```
docs/07_Infrastructure/Konfig-Matrix_Dev-ProZora.md
+31
View File
@@ -0,0 +1,31 @@
---
Konfigurations-Matrix
---
# Konfigurations-Matrix
### Dev-Umgebungen vs. Zora (Production)
| Variable | .env / .env.example (Dev Default) | Gitea-Secrets (Zora Production) | Zweck / Beschreibung |
|:----------------------------------|:----------------------------------------------------|:----------------------------------------------|:----------------------------------------------------------------------------------|
| **POSTGRES_SHARED_BUFFERS** | `256MB` (Default via Compose) | `16GB` | Hauptspeicher für DB-Caching (ca. 25% vom RAM). |
| **POSTGRES_EFFECTIVE_CACHE_SIZE** | `768MB` (Default via Compose) | `48GB` | Schätzwert für den OS-Cache (ca. 75% vom RAM). |
| **POSTGRES_USER** | `meldestelle` | `meldestelle` (oder eigener Secret-User) | Administrator-Nutzer der Datenbank. |
| **POSTGRES_PASSWORD** | `meldestelle` | `[STARKES_PASSWORT]` | Passwort für den DB-Zugriff (SSoT-Geheimnis). |
| **POSTGRES_DB** | `meldestelle` | `meldestelle` | Name der primären Datenbank-Instanz. |
| **POSTGRES_PORT** | `5432:5432` | `5432:5432` | Mapping vom Host zum Container. |
| **PROJECT_NAME** | `meldestelle` | `meldestelle` | Präfix für Container-Namen auf dem Host. |
| **KC_HOSTNAME** | `localhost` | `auth.mo-code.at` | Erreichbarkeit von Keycloak (wichtig für Tokens). |
| **KC_DB_URL** | `jdbc:postgresql://postgres:5432/pg-meldestelle-db` | `jdbc:postgresql://postgres:5432/meldestelle` | JDBC-String (muss zur POSTGRES_DB passen). |
| **VALKEY_MAXMEMORY** | `256mb` | `4gb` bis `8gb` | Zora hat 64 GB RAM; hier können wir großzügig cachen. |
| **VALKEY_POLICY** | `allkeys-lru` | `allkeys-lru` | Wirft die am längsten nicht genutzten Schlüssel raus, wenn der Speicher voll ist. |
| **VALKEY_PASSWORD** | `leer` oder `dev` | `[STARKES_SECRET]` | SSoT-Geheimnis aus Gitea-Secrets. |
| **VALKEY_PORT** | `6379:6379` | `6379:6379` | Standard-Port-Mapping. |
| **KC_HEAP_MAX** | `1024m` | `4096m` | Mehr Power für Zoras 64 GB RAM. |
| **KC_COMMAND** | `start-dev --import-realm` | `start --optimized` | Nutzt das im Dockerfile vor-gebaute Image. |
| **KC_HOSTNAME** | `localhost` | `auth.mo-code.at` | Wichtig für gültige Tokens im Web-Frontend. |
| **KC_DB_PASSWORD** | `meldestelle` | `[GEHEIM]` | SSoT-Passwort aus den Gitea-Secrets. |
| **KEYCLOAK_IMAGE_TAG** | `26.4` | `26.4` | Versionierung. |
| **ZIPKIN_HEAP** | `256m` | `1024m` | Mehr Puffer für Tracing-Daten auf Zora. |
| **CONSUL_IMAGE** | `hashicorp/consul:1.22.1` | `hashicorp/consul:1.22.1` | Versionierung. |
| **MP_MAX_MESSAGES** | `500` | `5000` | Mailpit Speicherlimit. |
docs/07_Infrastructure/Pangolin-vs-Cloudflare-Tunnel.md
+86
View File
@@ -0,0 +1,86 @@
---
Pangolin vs. Cloudflare Tunnel
---
## 🛡️ Pangolin vs. Cloudflare Tunnel
| Merkmal | Cloudflare Tunnel (`cloudflared`) | Pangolin (Self-Hosted) |
|------------------|---------------------------------------------|-------------------------------------------------|
| **Kontrolle** | Zentralisiert (Cloudflare sieht Traffic). | **Dezentral** (Du besitzt den VPS & Schlüssel). |
| **Datenschutz** | SSL terminiert bei Cloudflare. | **End-to-End** (SSL terminiert auf DEINEM VPS). |
| **AGB / Limits** | Verbot von Video-Streaming (Plex/Jellyfin). | **Keine Limits** (Du bestimmst den Traffic). |
| **Protokolle** | Primär TCP/HTTP. | **TCP & UDP** (Dank WireGuard-Basis). |
| **Kosten** | Kostenlos (Free Tier). | VPS-Miete (ca. 4€ bei Hetzner). |
| **Features** | WAF, DDoS-Schutz (proprietär). | SSO, CrowdSec, Geoblocking (Open Source). |
---
## 🚀 Deployment-Bauplan (Hetzner + MS-R1)
### Teil 1: VPS Setup (Hetzner Cloud)
1. Erstelle einen **CX21** VPS (Location: Frankfurt für geringste Latenz).
2. Installiere Docker und erstelle das Pangolin-Verzeichnis.
**Docker Compose für den VPS (`compose.yaml`):**
```yaml
services:
pangolin:
image: ghcr.io/m-pennat/pangolin:latest
container_name: pangolin
restart: unless-stopped
ports:
- "80:80" # HTTP (Let's Encrypt)
- "443:443" # HTTPS
- "51820:51820/udp" # WireGuard Tunnel
volumes:
- ./data:/var/lib/pangolin
- /var/run/docker.sock:/var/run/docker.sock
environment:
- PANGOLIN_DOMAIN=dashboard.deinedomain.de
```
*Nach dem Start (`docker compose up -d`) unter der Domain einloggen und einen neuen **Site-Client** anlegen, um den **Enrollment Token** zu erhalten.*
---
### Teil 2: Home-Server Setup (MS-R1 / Debian 12 arm64)
Auf deinem MS-R1 installierst du den Gegenpart **Newt**. Da du Debian 12 auf arm64 nutzt, ist das Setup extrem ressourcensparend.
**Docker Compose für den MS-R1 (`compose.yaml`):**
```yaml
services:
# Der Tunnel-Client
newt:
image: ghcr.io/m-pennat/newt:latest
container_name: newt
restart: unless-stopped
environment:
- NEWT_ENROLL_TOKEN=DEIN_TOKEN_VON_HETZNER_VPS
depends_on:
- gitea
# Dein Service (Beispiel: Gitea)
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: unless-stopped
volumes:
- ./gitea_data:/data
# Hinweis: Kein "ports"-Mapping nötig! Zugriff erfolgt über den Tunnel.
```
---
## 💡 Warum das für dich ein "Erfolg" ist
* **Kein Port-Forwarding:** Dein Router zu Hause bleibt komplett dicht.
* **Arm64-Optimiert:** Debian 12 und die Container nutzen kaum CPU-Zyklen deines MS-R1.
* **Identity-Aware Proxy:** Du kannst im Pangolin-Dashboard (Hetzner) mit drei Klicks einstellen, dass man sich erst per **Google** oder **GitHub** anmelden muss, um dein Gitea überhaupt zu sehen.
---
docs/07_Infrastructure/Zora_Infrastructure_Deployment_02-2026.md
+60
View File
@@ -0,0 +1,60 @@
---
Hier ist eine strategische Roadmap für den Ausbau des „Empires“ auf **Zora**. Da du aktuell im „Mo’s Territory“ bist, dient dieser Plan als Vorbereitung für deine nächste Session am Gerät.
:white_check_mark:
---
# Roadmap: Zora Infrastructure & Deployment (Februar 2026)
## Phase 1: Identity & CI/CD "Green Light"
**Ziel:** Den automatisierten Workflow scharf schalten und Berechtigungskonflikte lösen.
* ✅ **Gitea Secrets Finalisierung:** Erstellen der Secrets
* `REGISTRY_TOKEN` und
* `REGISTRY_USER` im Repository „Meldestelle“ (Umgehung der `GITEA_`-Namenssperre).
*[ ] **Runner-Stabilisierung:**
* Prüfen des Systemd-Status von `act_runner` im Container `infra-runner`.
*[ ] Sicherstellen, dass der Status im Gitea-Interface von „Inaktiv“ auf „Aktiv“ springt.
*[ ] **Erster Test-Build:**
* Erstellen eines Test-Projekts und
* Push aus der IDEA auslösen und das Log-Streaming in Gitea Actions verfolgen.
*[ ] Verifizieren, dass das Docker-Image in der Gitea-Registry (`git.mo-code.at`) landet.
---
## Phase 2: Core-Infrastructure Deployment
**Ziel:** Die Basis-Dienste (Datenbanken, Auth) in der `prod-meldestelle` zum Laufen bringen.
*[ ] **Umgebungs-Konfiguration:** * Vervollständigen der `/home/grandmo/meldestelle/.env` mit echten Passwörtern und
Keycloak-Secrets.
*[ ] **Stack-Launch (dc-infra.yaml):** * Start von **Postgres**, **Keycloak** und **Valkey** (Redis-Alternative).
*[ ] **Wichtig:** Kontrolle der Logs auf ARM64-Kompatibilität (`exec format error` vermeiden).
*[ ] **Netzwerk-Check:** * Testen der Erreichbarkeit von Zoras Mail-Relay (`10.0.6.1:25`) aus dem neuen Stack heraus.
---
## Phase 3: Application & Gateway Launch
**Ziel:** Den Ping-Service über das Spring Cloud Gateway erreichbar machen.
*[ ] **Backend-Start (dc-backend.yaml):** * Deployment des **api-gateways** und des **ping-services**.
*[ ] **Cloudflare-Tunnel Update:** * Hinzufügen der Route `api.mo-code.at`, die auf die IP der Meldestelle (`10.0.6.50`)
und den Port des Gateways (`8080`) zeigt.
*[ ] **Keycloak-Veredelung:** * Konfiguration des Realms und Erstellen des Clients für die Meldestelle im
Keycloak-Admin-Panel (via `auth.mo-code.at`).
---
## Phase 4: Resilience & Hardening
**Ziel:** Das System gegen äußere Einflüsse und Datenverlust absichern.
*[ ] **USV-Anbindung (NUT):** * Installation und Konfiguration der Network UPS Tools für die **Eaton 3S850D**.
*[ ] Test des Shutdown-Szenarios bei kritischem Akkustand.
*[ ] **Monitoring-Integration (dc-ops.yaml):** * Start von **Prometheus** und **Grafana**.
*[ ] Anbindung des Alertmanagers an das Postfix-Relay für E-Mail-Alarme.
*[ ] **Backup-Vollendung:** * Erweiterung des nächtlichen 03:00-Uhr-Skripts um die Sicherung der neuen Docker-Volumes in
`prod-meldestelle`.
docs/07_Infrastructure/Zora_System_Architektur.md
+74
View File
@@ -0,0 +1,74 @@
## 🏗️ 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/<service-name>`
* **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-<long>` (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.