kaffeekasse-saas/docs/deployment-proxy-guide.md

# 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`