From cb5922714c1a732c6b56c6c14f46825276998a01 Mon Sep 17 00:00:00 2001
From: cynfo3000 <cynfo3000@cynfo.net>
Date: Sat, 7 Mar 2026 00:33:38 +0100
Subject: [PATCH] docs: Nginx-Config mit API-Proxy + WebSocket-Support, vite
 ws:true

---
 docs/FRONTEND.md | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md
index 0cebb24..c70f66c 100644
--- a/docs/FRONTEND.md
+++ b/docs/FRONTEND.md
@@ -51,20 +51,25 @@ Dann `config.js` anpassen:
 
 ```js
 // frontend/src/config.js
-export const BACKEND_HOST = '192.168.85.13'        // IP des Backend-Servers
+export const BACKEND_HOST = '192.168.85.13'        // IP des Backend-Servers (für direkte Links, z.B. Tunnel-Ports)
 export const BACKEND_URL = `https://${BACKEND_HOST}:8443`
 export const API_KEY = 'DEIN_API_KEY'              // aus backend/config.yaml → api_keys[0]
 ```
 
+> **Hinweis:** API-Calls laufen im Produktivbetrieb über den Nginx-Proxy (`/api/` → Backend).
+> `BACKEND_HOST` wird nur noch für direkte Links verwendet (z.B. WebGUI-Tunnel-Ports).
+> `BACKEND_URL` wird im Dev-Server-Modus (Vite) für direkte API-Calls verwendet.
+
 Für die **lokale Entwicklung** (`npm run dev`) muss zusätzlich `vite.config.js` angepasst werden:
 
 ```js
 // vite.config.js → server.proxy
 proxy: {
   '/api': {
-    target: 'https://192.168.85.13:8443',  // Backend-IP eintragen
+    target: 'https://192.168.85.13:8443',  // Backend-IP anpassen
     changeOrigin: true,
     secure: false,
+    ws: true,  // WebSocket-Proxy aktivieren (Web Terminal, Agent-WS)
   }
 }
 ```
@@ -99,9 +104,14 @@ systemctl start nginx
 
 ---
 
-## 5. Nginx konfigurieren (Single-Page Application)
+## 5. Nginx konfigurieren
 
-React Router benötigt ein Nginx-Config das alle Routen auf `index.html` umleitet:
+React Router benötigt ein Nginx-Config das alle Routen auf `index.html` umleitet. Zusätzlich proxyt Nginx alle `/api/`-Requests zum Backend — das löst zwei Probleme:
+- **CORS** entfällt komplett (gleicher Origin)
+- **WebSocket-Verbindungen** (Web Terminal, Agent-WS) funktionieren ohne Browser-Zertifikatswarning
+
+> **Wichtig:** `proxy_ssl_verify off` ist nötig da das Backend ein selbstsigniertes Zertifikat verwendet.
+> **Wichtig:** `proxy_read_timeout 86400` ist nötig für lang laufende WebSocket-Verbindungen (Terminal, Tunnel).
 
 ```bash
 # Bestehende Default-Config ersetzen
@@ -113,6 +123,25 @@ server {
     root /var/www/html;
     index index.html;
 
+    # API Reverse-Proxy zum Backend (REST + WebSocket)
+    location /api/ {
+        client_max_body_size 50m;
+
+        proxy_pass https://192.168.85.13:8443;
+        proxy_ssl_verify off;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket-Support (Web Terminal, Agent-WS, Tunnel)
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 86400;
+    }
+
     # React SPA — alle Routen auf index.html
     location / {
         try_files $uri $uri/ /index.html;
@@ -137,6 +166,8 @@ rm -f /etc/nginx/sites-enabled/default
 nginx -t && systemctl reload nginx
 ```
 
+> **Backend-IP anpassen:** `192.168.85.13:8443` durch die tatsächliche Backend-Adresse ersetzen.
+
 ---
 
 ## 6. Deploy (auf dem Frontend-Server selbst)
@@ -194,11 +225,13 @@ Startet Vite Dev-Server auf `http://FRONTEND_IP:5173` mit Hot-Reload.
 API-Calls werden per Proxy an das Backend weitergeleitet — `vite.config.js` anpassen:
 
 ```js
+// vite.config.js
 proxy: {
   '/api': {
-    target: 'https://192.168.85.13:8443',  // Backend-IP
+    target: 'https://192.168.85.13:8443',  // Backend-IP anpassen
     changeOrigin: true,
     secure: false,
+    ws: true,  // WebSocket-Proxy (Web Terminal, Agent-WS)
   }
 }
 ```