docs: FRONTEND.md vollständig (Nginx, Node, config.js, deploy) + config.js aus Repo entfernt
This commit is contained in:
cynfo3000
parent
9bebf85a6d
commit
28ebb5378d
6
.gitignore
vendored
6
.gitignore
vendored
@ -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
|
||||
# ========================
|
||||
|
||||
264
docs/FRONTEND.md
264
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/
|
||||
│ ├── config.js # NICHT im Git — vor Build anlegen (s.o.)
|
||||
│ ├── config.example.js # Vorlage mit Platzhaltern
|
||||
│ ├── App.jsx # Router + ProtectedRoute
|
||||
│ ├── api/client.js # API Client (auth, agents, firmware, tunnels, etc.)
|
||||
│ ├── 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 + Outlet
|
||||
│ ├── layouts/AppLayout.jsx # Sidebar Navigation + Outlet
|
||||
│ ├── components/
|
||||
│ │ ├── AgentPanel.jsx # Side Panel mit Tabs (Uebersicht bis Agent)
|
||||
│ │ ├── 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
|
||||
│ ├── 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
|
||||
│ ├── SettingsPage.jsx # User-Management + Passwort
|
||||
│ └── Login.jsx # JWT Login
|
||||
├── vite.config.js
|
||||
├── vite.config.js # Vite Config (Proxy für Dev-Server)
|
||||
└── package.json
|
||||
```
|
||||
|
||||
6
frontend/src/config.example.js
Normal file
6
frontend/src/config.example.js
Normal file
@ -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'
|
||||
@ -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'
|
||||
Loading…
x
Reference in New Issue
Block a user