weitere Bearibeitung

2026-06-17 16:45:14 +02:00
parent 06645f1e9c
commit 1891ec0a51
38 changed files with 2720 additions and 109 deletions
@@ -0,0 +1,322 @@
+# Deployment Guide: Netcup Webspace & Code-Server Proxy
+
+Diese Anleitung erklärt, wie die Kaffeekasse-SaaS-Anwendung sowohl auf einem Netcup Webspace als auch über code-server Proxy-Weiterleitung betrieben werden kann.
+
+## Übersicht
+
+Die Anwendung ist so entwickelt, dass sie automatisch erkennt, ob sie:
+1. **Direkt** auf einem Webspace läuft (z.B. `https://example.com/`)
+2. **Hinter einem Reverse Proxy** läuft (z.B. `https://code-server.example.com/proxy/8080/`)
+
+## 1. Deployment auf Netcup Webspace
+
+### Voraussetzungen
+- PHP 8.0 oder höher
+- MySQL/MariaDB Datenbank
+- Apache mit mod_rewrite aktiviert
+- HTTPS-Zertifikat (Let's Encrypt empfohlen)
+
+### Schritte
+
+1. **Dateien hochladen**
+   ```bash
+   # Via FTP/SFTP alle Dateien hochladen
+   # Document Root sollte auf /public/ zeigen
+   ```
+
+2. **.env Datei konfigurieren**
+   ```bash
+   cp .env.example .env
+   nano .env
+   ```
+
+   Wichtige Einstellungen:
+   ```env
+   APP_URL=https://ihre-domain.de
+   APP_BASE_PATH=
+   
+   DB_HOST=localhost
+   DB_NAME=ihre_datenbank
+   DB_USER=ihr_benutzer
+   DB_PASS=ihr_passwort
+   
+   MAIL_FROM=noreply@ihre-domain.de
+   PASSWORD_RESET_URL=https://ihre-domain.de/reset-password?token={{token}}
+   ```
+
+3. **Verzeichnisrechte setzen**
+   ```bash
+   chmod 755 storage/
+   chmod 755 storage/cache/
+   chmod 755 storage/logs/
+   chmod 755 storage/uploads/
+   ```
+
+4. **Installation durchführen**
+   - Besuchen Sie `https://ihre-domain.de/install`
+   - Folgen Sie dem Setup-Assistenten
+
+### Apache Virtual Host Konfiguration (falls nötig)
+
+```apache
+<VirtualHost *:443>
+    ServerName ihre-domain.de
+    DocumentRoot /var/www/kaffeekasse/public
+    
+    <Directory /var/www/kaffeekasse/public>
+        Options -Indexes +FollowSymLinks
+        AllowOverride All
+        Require all granted
+    </Directory>
+    
+    # SSL Konfiguration
+    SSLEngine on
+    SSLCertificateFile /etc/letsencrypt/live/ihre-domain.de/fullchain.pem
+    SSLCertificateKeyFile /etc/letsencrypt/live/ihre-domain.de/privkey.pem
+</VirtualHost>
+```
+
+## 2. Deployment mit Code-Server Proxy
+
+### Voraussetzungen
+- Code-Server läuft und ist erreichbar
+- PHP 8.0+ CLI verfügbar
+- SQLite oder MySQL/MariaDB
+
+### Schritte
+
+1. **.env Datei konfigurieren**
+   ```env
+   APP_URL=http://localhost:8080
+   APP_BASE_PATH=/proxy/8080
+   
+   # Für SQLite (einfacher für Entwicklung)
+   DB_HOST=sqlite
+   DB_NAME=/config/workspace/kaffeeliste-neustart/storage/database.sqlite
+   
+   # Oder MySQL
+   DB_HOST=127.0.0.1
+   DB_NAME=kaffeekasse
+   DB_USER=root
+   DB_PASS=
+   ```
+
+2. **PHP Development Server starten**
+   ```bash
+   cd /config/workspace/kaffeeliste-neustart
+   php -S 0.0.0.0:8080 -t public public/router.php
+   ```
+
+3. **Zugriff über Code-Server Proxy**
+   - Die Anwendung ist nun erreichbar über:
+     `https://ihr-code-server.de/proxy/8080/`
+   
+   - Code-Server setzt automatisch den Header `X-Forwarded-Prefix`
+   - Die Anwendung erkennt dies und passt alle URLs an
+
+### Automatischer Start (Optional)
+
+Erstellen Sie ein Systemd-Service oder Screen-Session:
+
+```bash
+# Screen-Session
+screen -dmS kaffeekasse bash -c 'cd /config/workspace/kaffeeliste-neustart && php -S 0.0.0.0:8080 -t public public/router.php'
+
+# Später wieder verbinden
+screen -r kaffeekasse
+```
+
+## 3. Wie funktioniert die automatische Erkennung?
+
+### Base Path Detection
+
+Die Funktion `base_path()` in `app/Support/helpers.php` prüft in dieser Reihenfolge:
+
+1. **`$_SERVER['KAFFEEKASSE_PROXY_PREFIX']`** - Manuell gesetzter Prefix
+2. **`$_SERVER['HTTP_X_FORWARDED_PREFIX']`** - Von Code-Server gesetzt
+3. **`$_ENV['APP_BASE_PATH']`** - Aus .env Datei
+
+```php
+function base_path(): string
+{
+    foreach ([
+        $_SERVER['KAFFEEKASSE_PROXY_PREFIX'] ?? null,
+        $_SERVER['HTTP_X_FORWARDED_PREFIX'] ?? null,
+        $_ENV['APP_BASE_PATH'] ?? null,
+    ] as $prefix) {
+        $prefix = trim((string) $prefix);
+        
+        if ($prefix !== '') {
+            return normalize_base_path($prefix);
+        }
+    }
+    
+    return '';
+}
+```
+
+### URL-Generierung
+
+Alle URLs werden dynamisch generiert:
+
+```php
+// Beispiele
+url('/')                           // → / oder /proxy/8080/
+url('/admin/login')                // → /admin/login oder /proxy/8080/admin/login
+tenant_url('standort1', 'bookings') // → /t/standort1/bookings oder /proxy/8080/t/standort1/bookings
+asset_url('app.css')               // → /assets/app.css oder /proxy/8080/assets/app.css
+```
+
+### .htaccess Proxy-Unterstützung
+
+Die `.htaccess` leitet HTTPS-Informationen vom Proxy weiter:
+
+```apache
+# Proxy-Unterstützung: X-Forwarded-* Header durchreichen
+RewriteCond %{HTTP:X-Forwarded-Proto} ^https$
+RewriteRule ^ - [E=HTTPS:on]
+```
+
+## 4. Troubleshooting
+
+### Problem: URLs zeigen auf falschen Pfad
+
+**Lösung:** Prüfen Sie die Base Path Detection:
+
+```php
+// Temporär in public/index.php hinzufügen zum Debuggen
+var_dump([
+    'base_path' => base_path(),
+    'current_path' => current_path(),
+    'KAFFEEKASSE_PROXY_PREFIX' => $_SERVER['KAFFEEKASSE_PROXY_PREFIX'] ?? null,
+    'HTTP_X_FORWARDED_PREFIX' => $_SERVER['HTTP_X_FORWARDED_PREFIX'] ?? null,
+    'APP_BASE_PATH' => $_ENV['APP_BASE_PATH'] ?? null,
+]);
+```
+
+### Problem: CSS/Assets werden nicht geladen
+
+**Ursache:** Base Path wird nicht korrekt erkannt
+
+**Lösung:** Setzen Sie `APP_BASE_PATH` explizit in der `.env`:
+
+```env
+# Für Code-Server Proxy auf Port 8080
+APP_BASE_PATH=/proxy/8080
+
+# Für Subdirectory-Installation
+APP_BASE_PATH=/kaffeekasse
+```
+
+### Problem: Formular-Submissions funktionieren nicht
+
+**Ursache:** CSRF-Token oder falsche Action-URLs
+
+**Lösung:** 
+1. Prüfen Sie, ob Sessions funktionieren
+2. Stellen Sie sicher, dass alle Forms `<?= csrf_field($csrf) ?>` enthalten
+3. Verwenden Sie immer `url()` oder `tenant_url()` für Action-Attribute
+
+### Problem: Redirect-Loops
+
+**Ursache:** Proxy-Header werden nicht korrekt weitergeleitet
+
+**Lösung für Nginx Reverse Proxy:**
+```nginx
+location /proxy/8080/ {
+    proxy_pass http://localhost:8080/;
+    proxy_set_header X-Forwarded-Prefix /proxy/8080;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Host $host;
+}
+```
+
+## 5. Sicherheitshinweise
+
+### Für Netcup Webspace
+
+1. **HTTPS erzwingen** - Fügen Sie in `.htaccess` hinzu:
+   ```apache
+   RewriteCond %{HTTPS} off
+   RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
+   ```
+
+2. **Verzeichnisse schützen**
+   - Stellen Sie sicher, dass nur `/public` öffentlich erreichbar ist
+   - Dateien außerhalb von `/public` sollten nicht direkt aufrufbar sein
+
+3. **APP_KEY setzen**
+   ```bash
+   # Generieren Sie einen sicheren Key
+   php -r "echo bin2hex(random_bytes(32)) . PHP_EOL;"
+   ```
+
+### Für Code-Server
+
+1. **Nicht für Production verwenden**
+   - Code-Server Proxy ist für Entwicklung gedacht
+   - Für Production: Netcup Webspace oder dedizierter Server
+
+2. **Zugriffsbeschränkung**
+   - Schützen Sie Code-Server mit starkem Passwort
+   - Verwenden Sie HTTPS
+   - Beschränken Sie IP-Zugriff wenn möglich
+
+## 6. Migrations-Checkliste
+
+### Von Code-Server zu Netcup
+
+- [ ] Datenbank exportieren (falls SQLite → MySQL)
+- [ ] `.env` Datei anpassen (APP_URL, APP_BASE_PATH, DB_*)
+- [ ] Dateien via FTP/SFTP hochladen
+- [ ] Verzeichnisrechte setzen
+- [ ] Datenbank importieren
+- [ ] Installation testen
+- [ ] HTTPS-Zertifikat einrichten
+- [ ] Cron-Jobs einrichten (falls benötigt)
+
+### Von Netcup zu Code-Server
+
+- [ ] Datenbank exportieren
+- [ ] `.env` Datei anpassen (APP_BASE_PATH=/proxy/8080)
+- [ ] PHP Development Server starten
+- [ ] Über Proxy-URL testen
+
+## 7. Performance-Optimierung
+
+### Für Netcup Webspace
+
+1. **OPcache aktivieren** (php.ini):
+   ```ini
+   opcache.enable=1
+   opcache.memory_consumption=128
+   opcache.max_accelerated_files=10000
+   ```
+
+2. **Session-Speicher optimieren**:
+   ```ini
+   session.save_handler=files
+   session.save_path=/tmp
+   ```
+
+### Für Code-Server
+
+1. **SQLite für Entwicklung**:
+   - Schneller Setup
+   - Keine separate Datenbank nötig
+   - Gut für Tests
+
+2. **Development Server Optionen**:
+   ```bash
+   # Mit mehr Workers
+   php -S 0.0.0.0:8080 -t public public/router.php
+   ```
+
+## Support
+
+Bei Problemen:
+1. Prüfen Sie die Logs in `storage/logs/`
+2. Aktivieren Sie Debug-Modus: `APP_DEBUG=1` in `.env`
+3. Prüfen Sie PHP Error Logs
+4. Konsultieren Sie die Hauptdokumentation in `DEPLOY.md`