From 28ebb5378dbaff951d7009c1d6d2975663ce4c81 Mon Sep 17 00:00:00 2001 From: cynfo3000 Date: Fri, 6 Mar 2026 09:30:33 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20FRONTEND.md=20vollst=C3=A4ndig=20(Nginx?= =?UTF-8?q?,=20Node,=20config.js,=20deploy)=20+=20config.js=20aus=20Repo?= =?UTF-8?q?=20entfernt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 6 +- docs/FRONTEND.md | 276 ++++++++++++++++++++++++++------- frontend/src/config.example.js | 6 + frontend/src/config.js | 4 - 4 files changed, 229 insertions(+), 63 deletions(-) create mode 100644 frontend/src/config.example.js delete mode 100644 frontend/src/config.js diff --git a/.gitignore b/.gitignore index 2bf8052..b006251 100644 --- a/.gitignore +++ b/.gitignore @@ -29,11 +29,15 @@ build/ updater/rmm-updater # ======================== -# Frontend Build +# Frontend Build & Konfiguration # ======================== frontend/node_modules/ frontend/dist/ +# config.js hat echte IPs und API-Keys — nie einchecken +frontend/src/config.js +!frontend/src/config.example.js + # ======================== # OS / Editor # ======================== diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md index 0f5ef08..8ee0877 100644 --- a/docs/FRONTEND.md +++ b/docs/FRONTEND.md @@ -1,86 +1,246 @@ -# Frontend — Build & Deploy +# Frontend — Installation, Build & Deploy -React + Vite + TailwindCSS Web-Frontend, deployed als statische Dateien auf Nginx. +React + Vite + TailwindCSS Web-Frontend, deployed als statische Dateien über Nginx. ## Eckdaten -- **Server**: your-backend (Debian 13, Nginx) -- **Tech**: React 18, Vite, TailwindCSS, Recharts, Zustand, lucide-react -- **Theme**: Dark mit Orange-Akzent, komplett deutsch -- **Auth**: JWT Login (8h Token) -- **Default-Login**: `admin` / `YOUR_PASSWORD` +| | | +|---|---| +| **Tech** | React 18, Vite, TailwindCSS, Recharts, Zustand, lucide-react | +| **Theme** | Dark mit Orange-Akzent, komplett deutsch | +| **Auth** | JWT Login (8h Token) | +| **Standard-Login** | `admin` / `Start!123` (beim ersten Backend-Start angelegt) | +| **Frontend-Server** | separater LXC / Debian-Server mit Nginx | +| **Backend-Verbindung** | direkter HTTPS-API-Call zu `https://BACKEND_IP:8443` | -## Seiten +--- -| Seite | Beschreibung | -|-------|-------------| -| Dashboard | Uebersicht aller Firewalls, Status-Kacheln, AgentPanel per Klick | -| Firewalls | Suchbare Tabelle, AgentPanel mit Tabs (Uebersicht, Interfaces, Dienste, Tunnel, VPN, WireGuard, Routen, DHCP, Zertifikate, Backups, Agent); Firewall hinzufuegen/loeschen | -| Tunnel | Globale Tunnel-Uebersicht ueber alle Firewalls | -| Firmware | Multi-Plattform Firmware-Upload, Agent-Update-Trigger | -| Kunden | CRUD Kundenverwaltung | -| Einstellungen | Benutzerverwaltung, Passworte aendern | +## 1. Voraussetzungen (Build-System) -## Features (v1.0.3) +Build läuft auf dem Mac / Entwicklungsrechner, **nicht** auf dem Frontend-Server. -### Firewall hinzufuegen / Pre-Registration -- Dialog mit Name + optionalem Kunden -- Zeigt Installationsanleitung mit Copy-Buttons fuer die Shell-Befehle -- Agent wird mit `hostname="(ausstehend)"` angelegt, automatisches Matching bei Registration +```bash +# Node.js 20+ installieren (macOS mit Homebrew) +brew install node -### Firewall loeschen -- Papierkorb-Icon im AgentPanel -- Loescht Agent und alle zugehoerigen Daten (Systemdaten, Events, Backups, Metriken) +# Abhängigkeiten installieren (einmalig nach Clone) +cd frontend +npm install +``` -### OPNsense Business Edition Lizenz-Anzeige -Im **Uebersicht-Tab** des AgentPanel: -- Product Name (z.B. "OPNsense Business Edition") -- Subscription Key -- Ablaufdatum -- Restlaufzeit mit visuellem Farbbalken (gruen/gelb/rot je nach verbleibender Zeit) +--- -### Agent-Tab -- **Agent-Info**: Version, Agent-ID, Plattform, Uptime -- **Update-Button**: Direktes Agent-Update anfordern -- **Befehle**: Remote-Shell-Befehle direkt aus dem Frontend ausfuehren +## 2. Backend-URL konfigurieren -### Firmware-Seite -- Multi-Platform Upload (FreeBSD, Linux, Windows) -- Versions-Uebersicht pro Plattform mit SHA256-Hash und Groesse -- Agent-Update-Buttons (einzeln oder alle) +**VOR dem Build** muss `frontend/src/config.js` angelegt werden. +Die Datei ist in `.gitignore` und wird nicht eingecheckt (enthält echte IP + API-Key). -## Build & Deploy +```bash +cp frontend/src/config.example.js frontend/src/config.js +``` + +Dann `config.js` anpassen: + +```js +// frontend/src/config.js +export const BACKEND_HOST = '192.168.85.13' // IP des Backend-Servers +export const BACKEND_URL = `https://${BACKEND_HOST}:8443` +export const API_KEY = 'DEIN_API_KEY' // aus backend/config.yaml → api_keys[0] +``` + +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 + changeOrigin: true, + secure: false, + } +} +``` + +--- + +## 3. Build ```bash cd frontend -npm run build # ~330 KB JS, ~32 KB CSS -ssh root@your-backend 'rm -rf /var/www/html/assets/*' # Alte Hashes loeschen! -scp -r dist/* root@your-backend:/var/www/html/ +npm run build ``` -**Wichtig:** Vor Deploy immer `assets/` loeschen — Vite generiert Hash-basierte Dateinamen, alte Dateien bleiben sonst auf dem Server und Browser-Cache liefert 404. +Erzeugt `frontend/dist/` mit: +- `index.html` +- `assets/index-[hash].js` (~330 KB) +- `assets/index-[hash].css` (~32 KB) +- `vite.svg` + +--- + +## 4. Nginx auf dem Frontend-Server installieren + +```bash +# Debian 12/13 +apt update +apt install -y nginx + +systemctl enable nginx +systemctl start nginx +``` + +--- + +## 5. Nginx konfigurieren (Single-Page Application) + +React Router benötigt ein Nginx-Config das alle Routen auf `index.html` umleitet: + +```bash +# Bestehende Default-Config ersetzen +cat > /etc/nginx/sites-available/rmm-frontend << 'EOF' +server { + listen 80; + server_name _; + + root /var/www/html; + index index.html; + + # React SPA — alle Routen auf index.html + location / { + try_files $uri $uri/ /index.html; + } + + # Statische Assets mit Cache + location /assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # Kein Zugriff auf versteckte Dateien + location ~ /\. { + deny all; + } +} +EOF + +ln -sf /etc/nginx/sites-available/rmm-frontend /etc/nginx/sites-enabled/rmm-frontend +rm -f /etc/nginx/sites-enabled/default + +nginx -t && systemctl reload nginx +``` + +--- + +## 6. Deploy + +### Manuell + +```bash +cd frontend +npm run build +ssh root@FRONTEND_SERVER 'rm -rf /var/www/html/assets/*' # Alte Hashes löschen! +scp -r dist/* root@FRONTEND_SERVER:/var/www/html/ +ssh root@FRONTEND_SERVER 'nginx -s reload' +``` + +**Wichtig:** `assets/*` MUSS vor dem Deploy gelöscht werden — Vite generiert Hash-basierte +Dateinamen (`index-Dv2B5kJs.js`). Alte Dateien bleiben sonst auf dem Server und +der Browser-Cache liefert 404-Fehler. + +### Mit deploy-script (empfohlen) + +Das Skript `deploy-frontend.sh` im Root-Verzeichnis erledigt Build + Deploy + Nginx-Reload +in einem Schritt. Server-IP und Webroot am Anfang des Skripts anpassen: + +```bash +# deploy-frontend.sh — Variablen anpassen: +REMOTE="root@192.168.85.20" # IP des Frontend-Servers +WEB_ROOT="/var/www/html" + +# Dann ausführen: +./deploy-frontend.sh +``` + +--- + +## 7. Erster Login + +``` +URL: http://FRONTEND_SERVER_IP +Benutzer: admin +Passwort: Start!123 +``` + +Passwort sofort ändern unter **Einstellungen → Benutzer**. + +--- + +## 8. Lokale Entwicklung + +```bash +cd frontend +npm run dev +``` + +Startet Vite Dev-Server auf `http://localhost:5173` mit Hot-Reload. +API-Calls werden per Proxy an das Backend weitergeleitet (→ `vite.config.js` anpassen). + +--- + +## Seiten + +| Seite | Route | Beschreibung | +|-------|-------|-------------| +| Login | `/login` | JWT Login | +| Dashboard | `/` | Status-Kacheln, Agent-Liste, AgentPanel per Klick | +| Firewalls | `/agents` | Suchbare Tabelle, AgentPanel mit Tabs, Hinzufügen/Löschen | +| Tunnel | `/tunnels` | Globale Tunnel-Übersicht über alle Firewalls | +| Firmware | `/firmware` | Multi-Plattform Upload, Agent-Update-Trigger | +| Kunden | `/customers` | CRUD Kundenverwaltung | +| Einstellungen | `/settings` | Benutzerverwaltung, Passwörter ändern | + +## AgentPanel Tabs + +| Tab | Inhalt | +|-----|--------| +| Übersicht | Hardware, OS, Uptime, CPU/RAM, Lizenz (Business Edition) | +| Interfaces | Netzwerk-Interfaces mit IP, MAC, Status, RX/TX | +| Dienste | Laufende Services mit Status-Badge | +| Tunnel | Quick-Buttons (WebGUI, SSH, Custom), aktive Tunnel | +| VPN | WireGuard-Instanzen mit Transfer-Statistiken | +| WireGuard | Peer-Management (CRUD), Client-Config mit Copy-Button | +| Routen | Routing-Tabelle | +| DHCP | Aktive Leases mit Suche (IP, MAC, Hostname) | +| Zertifikate | Karten-Layout mit Ablaufdatum und Fortschrittsbalken | +| Backups | Config-Backup erstellen, Liste, Download als XML | +| Agent | Version, Agent-ID, Update-Button, Remote-Befehle | + +--- ## Dateistruktur ``` frontend/ ├── src/ -│ ├── App.jsx # Router + ProtectedRoute -│ ├── api/client.js # API Client (auth, agents, firmware, tunnels, etc.) -│ ├── stores/auth.js # Zustand Auth Store (JWT Token) -│ ├── layouts/AppLayout.jsx # Sidebar + Outlet +│ ├── config.js # NICHT im Git — vor Build anlegen (s.o.) +│ ├── config.example.js # Vorlage mit Platzhaltern +│ ├── App.jsx # Router + ProtectedRoute +│ ├── main.jsx # Entry Point +│ ├── index.css # TailwindCSS + Custom Styles +│ ├── api/client.js # API Client (alle Endpoints) +│ ├── stores/auth.js # Zustand Auth Store (JWT Token) +│ ├── layouts/AppLayout.jsx # Sidebar Navigation + Outlet │ ├── components/ -│ │ ├── AgentPanel.jsx # Side Panel mit Tabs (Uebersicht bis Agent) -│ │ └── StatusBadge.jsx # Online/Offline/Stale Badge +│ │ ├── AgentPanel.jsx # Side Panel mit 11 Tabs +│ │ └── StatusBadge.jsx # Online/Offline/Stale Badge │ └── pages/ -│ ├── Dashboard.jsx # Status-Kacheln + Agent-Liste -│ ├── Agents.jsx # Firewall-Tabelle -│ ├── AgentDetail.jsx # Detail-Ansicht (full page) -│ ├── Tunnels.jsx # Globale Tunnel-Uebersicht -│ ├── Firmware.jsx # Multi-Plattform Firmware + Update-Trigger -│ ├── Customers.jsx # Kunden CRUD -│ ├── SettingsPage.jsx # User-Management -│ └── Login.jsx # JWT Login -├── vite.config.js +│ ├── Dashboard.jsx # Status-Kacheln + Agent-Liste +│ ├── Agents.jsx # Firewall-Tabelle + Pre-Registration +│ ├── Tunnels.jsx # Globale Tunnel-Übersicht +│ ├── Firmware.jsx # Multi-Plattform Firmware + Updates +│ ├── Customers.jsx # Kunden CRUD +│ ├── SettingsPage.jsx # User-Management + Passwort +│ └── Login.jsx # JWT Login +├── vite.config.js # Vite Config (Proxy für Dev-Server) └── package.json ``` diff --git a/frontend/src/config.example.js b/frontend/src/config.example.js new file mode 100644 index 0000000..ec32ef4 --- /dev/null +++ b/frontend/src/config.example.js @@ -0,0 +1,6 @@ +// Frontend-Konfiguration — VOR dem Build anpassen, dann als config.js speichern +// config.js ist in .gitignore und wird NICHT eingecheckt + +export const BACKEND_HOST = 'BACKEND_IP_ODER_HOSTNAME' +export const BACKEND_URL = `https://${BACKEND_HOST}:8443` +export const API_KEY = 'DEIN_API_KEY' diff --git a/frontend/src/config.js b/frontend/src/config.js deleted file mode 100644 index 92a15a9..0000000 --- a/frontend/src/config.js +++ /dev/null @@ -1,4 +0,0 @@ -// Frontend-Konfiguration — bei Deployment anpassen -export const BACKEND_HOST = '192.168.85.13' -export const BACKEND_URL = `https://${BACKEND_HOST}:8443` -export const API_KEY = '01532e5a7c9e70bf2757df77a2f5b9b9'