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

Netcup Deployment Guide - Kaffeekasse SaaS

Dieser Guide führt Sie Schritt für Schritt durch das Deployment der Kaffeekasse SaaS auf Netcup Webspace.

Übersicht

Die Kaffeekasse SaaS ist bereits vollständig für Netcup Webspace vorbereitet. Dieses Deployment-Guide ergänzt die bestehende Dokumentation (DEPLOY.md, docs/go-live-checklist-netcup.md) um praktische Schritte.

Voraussetzungen

• Netcup Webspace mit PHP 8.3+ und MySQL
• FTP/SFTP Zugang zu Ihrem Webspace
• Domain oder Subdomain für die Anwendung

Schritt 1: Lokale Vorbereitung

1.1 Deployment-Skript ausführen

# Im Projektverzeichnis
./scripts/deploy-netcup.sh

Das Skript erstellt:

• Ein Release-Paket (build/kaffeekasse-saas-YYYYMMDD-HHMMSS.tar.gz)
• Deployment-Anweisungen
• .htaccess Informationen

1.2 Umgebungskonfiguration anpassen

Bearbeiten Sie .env.netcup und passen Sie folgende Werte an:

APP_URL=https://ihre-domain.tld
APP_KEY=ihr-32-stelliger-app-schluessel
DB_NAME=ihre_datenbank
DB_USER=ihr_db_benutzer
DB_PASS=ihr_db_passwort
MAIL_FROM=noreply@ihre-domain.tld
MAIL_REPLY_TO=support@ihre-domain.tld
RFID_SHARED_SECRET=ihr-sicherer-rfid-schluessel

Wichtig: Generieren Sie sichere, zufällige Werte für APP_KEY und RFID_SHARED_SECRET!

Schritt 2: Netcup Webspace vorbereiten

2.1 Domain/Subdomain einrichten

1. Loggen Sie sich in das Netcup WCP (Webhosting Control Panel) ein
2. Erstellen Sie eine neue Domain oder Subdomain
3. Setzen Sie den Document Root auf: /apps/kaffeekasse/current/public

2.2 MySQL Datenbank erstellen

1. Erstellen Sie eine neue MySQL Datenbank
2. Erstellen Sie einen separaten Datenbankbenutzer
3. Gewähren Sie dem Benutzer alle Rechte auf die Datenbank
4. Notieren Sie sich die Zugangsdaten für die .env Datei

2.3 PHP Version einstellen

1. Stellen Sie die PHP Version auf 8.3 oder 8.4
2. Aktivieren Sie alle benötigten PHP Extensions (PDO, MySQL, etc.)

Schritt 3: Upload und Installation

3.1 Dateien hochladen

# Per SFTP/FTP
# 1. Release-Paket nach /apps/kaffeekasse/ hochladen
# 2. .env.netcup als .env nach /apps/kaffeekasse/ hochladen

3.2 Entpacken und einrichten

# Auf dem Server (SSH) oder per File Manager
cd /apps/kaffeekasse
tar -xzf kaffeekasse-saas-*.tar.gz
mv kaffeekasse-saas-* current
mv .env current/

3.3 Verzeichnisberechtigungen

Stellen Sie sicher, dass folgende Verzeichnisse beschreibbar sind:

• storage/
• storage/cache/
• storage/logs/
• storage/uploads/

Schritt 4: Installation

Option A: Browser-Installer (empfohlen)

1. Öffnen Sie https://ihre-domain.tld/install
2. Folgen Sie den Anweisungen des Installers
3. Der Installer erstellt automatisch die Datenbanktabellen

Option B: Manuelle Installation

# Per SSH auf dem Server
/usr/local/php83/bin/php /apps/kaffeekasse/current/bin/migrate.php

Schritt 5: Cron-Jobs einrichten

5.1 Hauptcron (alle 5 Minuten)

*/5 * * * * /usr/local/php83/bin/php /apps/kaffeekasse/current/bin/cron.php

5.2 Healthcheck (täglich)

0 6 * * * /usr/local/php83/bin/php /apps/kaffeekasse/current/bin/healthcheck.php

Schritt 6: SSL/HTTPS einrichten

1. Aktivieren Sie Let's Encrypt in Ihrem WCP
2. Erzwingen Sie HTTPS für die Domain
3. Testen Sie die SSL-Konfiguration

Schritt 7: Tests durchführen

7.1 Grundfunktionen testen

1. Startseite: https://ihre-domain.tld
2. Admin-Login: https://ihre-domain.tld/admin/login
3. Healthcheck:

   /usr/local/php83/bin/php /apps/kaffeekasse/current/bin/healthcheck.php
   

7.2 Vollständiger Test

1. Loggen Sie sich als Admin ein
2. Erstellen Sie einen Test-Mandanten
3. Loggen Sie sich als Mandant ein
4. Erstellen Sie Testprodukte und -buchungen
5. Prüfen Sie die Cron-Ausführung

Schritt 8: Produktionsbereitschaft

8.1 Sicherheitscheck

• Nur public/ ist über Web erreichbar
• .env, .git, Backups sind nicht öffentlich zugänglich
• HTTPS ist erzwungen
• Starke Passwörter für Admin und DB

8.2 Backup einrichten

• Tägliches DB-Backup
• .env Datei sichern
• storage/uploads sichern
• Release-Artefakte aufbewahren

8.3 Monitoring

• Externes Uptime-Monitoring
• Log-Überwachung
• Cron-Job Überwachung

Troubleshooting

Häufige Probleme

Problem: 500 Internal Server Error

• Lösung: Prüfen Sie Apache Error Logs und PHP Error Logs
• Häufige Ursache: Falsche Dateiberechtigungen oder .htaccess Probleme

Problem: Datenbank-Verbindungsfehler

• Lösung: Prüfen Sie DB-Zugangsdaten in .env
• Tipp: Testen Sie die Verbindung mit einem separaten PHP-Skript

Problem: Cron-Jobs laufen nicht

• Lösung: Prüfen Sie PHP-Pfad und Dateiberechtigungen
• Tipp: Testen Sie Cron-Jobs manuell per SSH

Log-Dateien

• Apache Error Log: Meist in /var/log/apache2/error.log oder über WCP
• PHP Error Log: Konfigurierbar in PHP-Einstellungen
• Application Logs: storage/logs/

Support und weitere Informationen

• Vollständige Checkliste: docs/go-live-checklist-netcup.md
• Deployment-Dokumentation: DEPLOY.md
• Betriebshandbuch: RUNBOOK.md

Nächste Schritte nach Go-Live

1. Überwachen Sie die Anwendung in den ersten Tagen intensiv
2. Richten Sie regelmäßige Backups ein
3. Planen Sie Updates und Wartungsfenster
4. Dokumentieren Sie Ihre spezifische Konfiguration

---

Hinweis: Dieser Guide basiert auf der aktuellen Netcup Webspace-Konfiguration. Bei Änderungen der Hosting-Umgebung können Anpassungen erforderlich sein.