refactoring Dokumentation

2025-10-15 12:48:00 +02:00
parent e8f33e465c
commit be464f2ac0
42 changed files with 1155 additions and 13101 deletions
@@ -0,0 +1,53 @@
+---
+owner: ops-team
+status: active
+review_cycle: 180d
+last_reviewed: 2025-10-15
+summary: Anleitung zur Installation und Konfiguration des Nginx Reverse Proxys auf dem Proxmox-Host für die Meldestelle-Services.
+---
+
+# How-To: Proxmox/Nginx Reverse Proxy deployen
+
+Diese Anleitung beschreibt die Einrichtung des Nginx Reverse Proxys auf dem Proxmox-Host. Die Beispielkonfiguration liegt im Repository und wird unverändert übernommen.
+
+- Beispielkonfiguration: proxmox-nginx/meldestelle.conf
+
+## Voraussetzungen
+- Proxmox-Host mit root-/sudo-Zugang
+- Installiertes Nginx (`apt install nginx`)
+- Lokale Container-Services laufen auf dem Host und sind über `localhost` erreichbar (Web 4000, Gateway 8081, VNC 6080)
+
+## Schritte
+1) Konfigurationsdatei auf den Host kopieren
+```bash
+sudo cp docs/proxmox-nginx/meldestelle.conf /etc/nginx/sites-available/
+```
+
+2) Site aktivieren (Symlink anlegen)
+```bash
+sudo ln -s /etc/nginx/sites-available/meldestelle.conf /etc/nginx/sites-enabled/
+```
+
+3) Nginx Konfiguration testen und neu laden
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+4) DNS konfigurieren (Beispiele)
+- meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
+- api.meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
+- vnc.meldestelle.yourdomain.com → öffentliche IP deines Proxmox-Hosts
+
+5) Health-Checks
+```bash
+curl -i http://api.meldestelle.yourdomain.com/actuator/health
+curl -i http://meldestelle.yourdomain.com/health
+```
+
+## HTTPS (optional)
+In der Beispielkonfiguration sind HTTPS-Serverblöcke und HTTP→HTTPS Redirects als Kommentar enthalten. Aktiviere diese Blöcke, wenn du Zertifikate (Let's Encrypt/Cloudflare) eingerichtet hast. Datei: proxmox-nginx/meldestelle.conf
+
+## Fehlerbehebung
+- 502 Bad Gateway: Zielcontainer läuft nicht oder Port falsch → Dienste starten (`make full-up`) und Ports prüfen.
+- CORS-Fehler: API ausschließlich über die `api.*`-Domain aufrufen; Web-App über `meldestelle.*`.
+- Änderungen ohne Effekt: `nginx -t` ausführen und `systemctl reload nginx`.
@@ -0,0 +1,67 @@
+---
+owner: project-maintainers
+status: active
+review_cycle: 90d
+last_reviewed: 2025-10-15
+summary: Kürzeste Anleitung, um das komplette System lokal zu starten und zu prüfen, ob alles läuft.
+---
+
+# How-To: Lokale Umgebung starten (Quickstart)
+
+Diese Kurz-Anleitung bringt deine lokale Umgebung in wenigen Minuten zum Laufen.
+
+## Starten
+- Komplettes System (Infra + Services + Clients)
+```bash
+make full-up
+```
+
+- Nur Backend (Infra + Gateway + Microservices)
+```bash
+make services-up
+```
+
+- Nur Clients (Infra + Web-App)
+```bash
+make clients-up
+```
+
+Logs ansehen (z. B. Backend):
+```bash
+make services-logs
+```
+
+## Wichtige URLs
+- Web App: http://localhost:4000
+- API Gateway: http://localhost:8081 (Health: /actuator/health)
+- Keycloak (Auth): http://localhost:8180
+- Consul (Service Discovery): http://localhost:8500
+
+Weitere Ports findest du unter: reference/ports-and-urls.md
+
+## Health-Checks
+```bash
+# Gateway
+curl -i http://localhost:8081/actuator/health
+
+# Web-App (falls vorhanden)
+curl -i http://localhost:4000/health || true
+```
+
+## Auth (Keycloak)
+- Admin-Login (default): http://localhost:8180
+  - Username: KC_BOOTSTRAP_ADMIN_USERNAME (default: admin)
+  - Password: KC_BOOTSTRAP_ADMIN_PASSWORD (default: admin)
+- Beim ersten Start wird der Realm aus docker/services/keycloak/meldestelle-realm.json importiert.
+
+## Häufige Probleme
+- Dienste nicht erreichbar → Containers laufen? `make full-logs` bzw. `make services-logs` prüfen.
+- 401/403 beim API-Aufruf → Prüfen, ob ein gültiges Bearer-Token gesendet wird und Keycloak erreichbar ist.
+- CORS im Browser → API über das Gateway (http://localhost:8081) aufrufen und nicht direkt die Services (8082–8086).
+- Port-Kollisionen → Belegte Ports mit `lsof -i :PORT` prüfen oder Ports anpassen.
+
+## Stoppen
+```bash
+make full-down
+# oder spezifisch: make services-down / make clients-down / make infrastructure-down
+```