Bugfix and Docs

2026-03-10 13:12:57 +00:00
parent 3516ff8486
commit ac4d77dddf
75 changed files with 3511 additions and 5142 deletions
--- a/docs/deployment/development.md
+++ b/docs/deployment/development.md
@@ -5,7 +5,7 @@
 ## Voraussetzungen

 - Node.js >= 20.19.0
- Alle [externen Tools](../getting-started/prerequisites.md) installiert
+- externe Tools installiert (`makemkvcon`, `HandBrakeCLI`, `mediainfo`)

 ---

@@ -15,15 +15,18 @@
 ./start.sh
 ```

-Das Skript startet automatisch:
- **Backend** auf Port 3001 (mit Nodemon für Hot-Reload)
- **Frontend** auf Port 5173 (mit Vite HMR)
+Startet:
+
+- Backend (`http://localhost:3001`, mit nodemon)
+- Frontend (`http://localhost:5173`, mit Vite HMR)
+
+Stoppen: `Ctrl+C`.

 ---

-## Manuelle Entwicklungsumgebung
+## Manuell

-### Terminal 1 – Backend
+### Backend

 ```bash
 cd backend
@@ -31,9 +34,7 @@ npm install
 npm run dev
 ```

-Backend läuft auf `http://localhost:3001` mit **Nodemon** – Neustart bei Dateiänderungen.
-
-### Terminal 2 – Frontend
+### Frontend

 ```bash
 cd frontend
@@ -41,97 +42,44 @@ npm install
 npm run dev
 ```

-Frontend läuft auf `http://localhost:5173` mit **Vite HMR** – sofortige Browser-Updates.
+---
+
+## Vite-Proxy (Dev)
+
+`frontend/vite.config.js` proxied standardmäßig:
+
+- `/api` -> `http://127.0.0.1:3001`
+- `/ws` -> `ws://127.0.0.1:3001`

 ---

-## Vite-Proxy
+## Remote-Dev (optional)

-Im Entwicklungsmodus proxied Vite alle API- und WebSocket-Anfragen zum Backend:
-
-```js
-// frontend/vite.config.js
-server: {
-  proxy: {
-    '/api': {
-      target: 'http://localhost:3001',
-      changeOrigin: true
-    },
-    '/ws': {
-      target: 'ws://localhost:3001',
-      ws: true
-    }
-  }
-}
-```
-
-Das bedeutet: Im Browser macht das Frontend Anfragen an `localhost:5173/api/...` – Vite leitet diese an `localhost:3001/api/...` weiter.
-
---
-
-## Remote-Entwicklung
-
-Falls Ripster auf einem entfernten Server entwickelt wird (z.B. Homeserver), muss die Vite-Konfiguration angepasst werden:
+Beispiel `frontend/.env.local`:

 ```env
-# frontend/.env.local
-VITE_API_BASE=http://192.168.1.100:3001
-VITE_WS_URL=ws://192.168.1.100:3001
+VITE_API_BASE=http://192.168.1.100:3001/api
+VITE_WS_URL=ws://192.168.1.100:3001/ws
+VITE_PUBLIC_ORIGIN=http://192.168.1.100:5173
+VITE_ALLOWED_HOSTS=192.168.1.100,ripster.local
+VITE_HMR_PROTOCOL=ws
 VITE_HMR_HOST=192.168.1.100
-VITE_HMR_PORT=5173
+VITE_HMR_CLIENT_PORT=5173
 ```

 ---

-## Log-Level für Entwicklung
-
-```env
-# backend/.env
-LOG_LEVEL=debug
-```
-
-Im Debug-Modus werden alle Ausgaben der externen Tools (MakeMKV, HandBrake) vollständig geloggt.
-
---
-
-## Stoppen
+## Nützliche Kommandos

 ```bash
-./kill.sh
+# Root dev (backend + frontend)
+npm run dev
+
+# einzeln
+npm run dev:backend
+npm run dev:frontend
+
+# Frontend Build
+npm run build:frontend
 ```

---
-
-## Linting & Type-Checking
-
-```bash
-# Frontend (ESLint)
-cd frontend && npm run lint
-
-# Backend hat keine separaten Lint-Scripts,
-# nutze direkt eslint falls konfiguriert
-```
-
---
-
-## Deployment-Script
-
-Das `deploy-ripster.sh`-Script überträgt Code auf einen Remote-Server per SSH:
-
-```bash
-./deploy-ripster.sh
-```
-
-**Was das Script tut:**
-1. `rsync` synchronisiert den Code (Backend-Quellcode ohne `data/`)
-2. Die Datenbank (`backend/data/`) wird **nicht** überschrieben
-3. Verbindung via SSH (konfigurierbar im Script)
-
-**Anpassung des Scripts:**
-
-```bash
-# deploy-ripster.sh
-REMOTE_HOST="192.168.1.100"
-REMOTE_USER="michael"
-REMOTE_PATH="/home/michael/ripster"
-```
--- a/docs/deployment/production.md
+++ b/docs/deployment/production.md
@@ -4,42 +4,44 @@

 ## Empfohlene Architektur

+```text
+Client
+  -> nginx (Reverse Proxy + statisches Frontend)
+    -> Backend API/WebSocket (Node.js, Port 3001)
 ```
-Internet / Heimnetz
-        ↓
-   nginx (Reverse Proxy)
-        ↓
-   ┌────┴────┐
-   │         │
-Backend   Frontend
- :3001     (statische Dateien)
-```
+
+Wichtig: Das Backend serviert im aktuellen Stand keine `frontend/dist`-Dateien automatisch.

 ---

-## systemd-Service
-
-Für ein dauerhaftes Betreiben als systemd-Service:
+## 1) Frontend builden

 ```bash
-sudo nano /etc/systemd/system/ripster.service
+cd frontend
+npm install
+npm run build
 ```

+Artefakte liegen in `frontend/dist/`.
+
+---
+
+## 2) Backend als systemd-Service
+
+Beispiel `/etc/systemd/system/ripster-backend.service`:
+
 ```ini
 [Unit]
-Description=Ripster - Disc Ripping Service
+Description=Ripster Backend
 After=network.target

 [Service]
 Type=simple
-User=michael
-WorkingDirectory=/home/michael/ripster
-ExecStart=/bin/bash /home/michael/ripster/start.sh
-ExecStop=/bin/bash /home/michael/ripster/kill.sh
+User=ripster
+WorkingDirectory=/opt/ripster/backend
+ExecStart=/usr/bin/env node src/index.js
 Restart=on-failure
-RestartSec=10s
-
-# Umgebungsvariablen
+RestartSec=5
 Environment=NODE_ENV=production
 Environment=PORT=3001
 Environment=LOG_LEVEL=info
@@ -48,61 +50,40 @@ Environment=LOG_LEVEL=info
 WantedBy=multi-user.target
 ```

+Aktivieren:
+
 ```bash
-# Service aktivieren und starten
 sudo systemctl daemon-reload
-sudo systemctl enable ripster
-sudo systemctl start ripster
-
-# Status prüfen
-sudo systemctl status ripster
-
-# Logs anzeigen
-journalctl -u ripster -f
+sudo systemctl enable --now ripster-backend
+sudo systemctl status ripster-backend
 ```

 ---

-## Frontend-Build
+## 3) nginx konfigurieren

-Für Produktion das Frontend bauen:
-
-```bash
-cd frontend
-npm run build
-```
-
-Die statischen Dateien landen in `frontend/dist/`.
-
---
-
-## nginx-Konfiguration
+Beispiel `/etc/nginx/sites-available/ripster`:

 ```nginx
-# /etc/nginx/sites-available/ripster
 server {
    listen 80;
    server_name ripster.local;

-    # Statisches Frontend
-    root /home/michael/ripster/frontend/dist;
+    root /opt/ripster/frontend/dist;
    index index.html;

-    # SPA Fallback (React Router)
    location / {
        try_files $uri $uri/ /index.html;
    }

-    # API-Proxy zum Backend
    location /api/ {
-        proxy_pass http://localhost:3001;
+        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

-    # WebSocket-Proxy
    location /ws {
-        proxy_pass http://localhost:3001;
+        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
@@ -111,83 +92,27 @@ server {
 }
 ```

+Aktivieren:
+
 ```bash
 sudo ln -s /etc/nginx/sites-available/ripster /etc/nginx/sites-enabled/
-sudo nginx -t && sudo systemctl reload nginx
+sudo nginx -t
+sudo systemctl reload nginx
 ```

 ---

-## Nur-Backend-Produktion (ohne nginx)
-
-Falls kein Reverse Proxy gewünscht ist, kann das Backend die Frontend-Dateien direkt ausliefern:
-
-```bash
-# Frontend bauen
-cd frontend && npm run build
-
-# Backend startet und serviert frontend/dist/
-cd backend && NODE_ENV=production npm start
-```
-
-Das Backend ist so konfiguriert, dass es im Produktionsmodus die `frontend/dist/`-Dateien als statische Assets ausliefert.
-
---
-
 ## Datenbank-Backup

 ```bash
-# Datenbank sichern
-cp backend/data/ripster.db backend/data/ripster.db.backup.$(date +%Y%m%d)
-
-# Oder mit SQLite-eigenem Backup-Befehl
-sqlite3 backend/data/ripster.db ".backup '/mnt/backup/ripster.db'"
-```
-
-!!! tip "Automatisches Backup"
-    Cron-Job für tägliches Backup:
-    ```cron
-    0 3 * * * sqlite3 /home/michael/ripster/backend/data/ripster.db ".backup '/mnt/backup/ripster-$(date +\%Y\%m\%d).db'"
-    ```
-
---
-
-## Log-Rotation
-
-Ripster rotiert Logs automatisch täglich. Falls zusätzlich systemd-Journal-Rotation gewünscht ist:
-
-```bash
-# /etc/logrotate.d/ripster
-/home/michael/ripster/backend/logs/*.log {
-    daily
-    rotate 14
-    compress
-    missingok
-    notifempty
-}
+sqlite3 /opt/ripster/backend/data/ripster.db \
+  ".backup '/var/backups/ripster-$(date +%Y%m%d).db'"
 ```

 ---

-## Sicherheitshinweise
+## Sicherheit

-!!! warning "Heimnetz-Einsatz"
-    Ripster ist für den Einsatz im **lokalen Heimnetz** konzipiert und enthält **keine Authentifizierung**. Stelle sicher, dass der Dienst nicht öffentlich erreichbar ist.
-
-Falls öffentlicher Zugang benötigt wird:
-
-1. **Basic Auth** via nginx:
-   ```bash
-   sudo htpasswd -c /etc/nginx/.htpasswd michael
-   ```
-   ```nginx
-   location / {
-       auth_basic "Ripster";
-       auth_basic_user_file /etc/nginx/.htpasswd;
-       # ...
-   }
-   ```
-
-2. **VPN-Zugang** (empfohlen): Zugriff nur über WireGuard/OpenVPN
-
-3. **SSL/TLS**: Let's Encrypt mit certbot für HTTPS
+- Ripster hat keine eingebaute Authentifizierung.
+- Für externen Zugriff mindestens Basic Auth + TLS + Netzwerksegmentierung/VPN einsetzen.
+- Secrets nicht ins Repo committen (`.env`, Settings-Felder).