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

   # Via FTP/SFTP alle Dateien hochladen
   # Document Root sollte auf /public/ zeigen
   

2. .env Datei konfigurieren

   cp .env.example .env
   nano .env
   

   Wichtige Einstellungen:

   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

   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)

<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

   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

   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:

# 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

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:

// 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:

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

// 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:

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

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:

   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

   # 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):

   opcache.enable=1
   opcache.memory_consumption=128
   opcache.max_accelerated_files=10000
   

2. Session-Speicher optimieren:

   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:

   # 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