7288b93500
Add neutral diagnostic framework for future reporting modules: - DiagnosticReporterInterface, Registry, Manager, PayloadSanitizer - Laravel exception hook in bootstrap/app.php - Module permission declarations (requires_permissions in module.json) - Core diagnostic report points (module boot/install/update failures) - Module documentation update (moduldoku.md) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
295 lines
10 KiB
Markdown
295 lines
10 KiB
Markdown
# Schneespur — Installationsanleitung
|
|
|
|
Diese Anleitung beschreibt die Installation von Schneespur auf einem klassischen Shared-Webhosting (Strato, IONOS, All-Inkl o. ä.) mit PHP und MySQL. SSH oder Docker sind **nicht** erforderlich.
|
|
|
|
---
|
|
|
|
## Inhaltsverzeichnis
|
|
|
|
1. [Systemvoraussetzungen](#1-systemvoraussetzungen)
|
|
2. [Dateien hochladen](#2-dateien-hochladen)
|
|
3. [Document-Root konfigurieren](#3-document-root-konfigurieren)
|
|
4. [Datenbank anlegen](#4-datenbank-anlegen)
|
|
5. [Installations-Assistent](#5-installations-assistent)
|
|
6. [Cron-Job einrichten](#6-cron-job-einrichten)
|
|
7. [OwnTracks einrichten](#7-owntracks-einrichten)
|
|
8. [Update-Anleitung](#8-update-anleitung)
|
|
9. [Backup](#9-backup)
|
|
10. [Troubleshooting](#10-troubleshooting)
|
|
|
|
---
|
|
|
|
## 1. Systemvoraussetzungen
|
|
|
|
| Anforderung | Minimum | Empfohlen |
|
|
|-------------|---------|-----------|
|
|
| PHP | 8.2 | 8.3 oder 8.4 |
|
|
| MySQL | 5.7 | 8.0+ |
|
|
| MariaDB (alternativ) | 10.3 | 10.6+ |
|
|
|
|
### Benötigte PHP-Erweiterungen
|
|
|
|
**Pflicht** (Installation schlägt ohne diese fehl):
|
|
|
|
- `pdo_mysql`
|
|
- `gd`
|
|
|
|
**Empfohlen** (Warnungen im Assistenten, wenn fehlend):
|
|
|
|
- `mbstring`
|
|
- `openssl`
|
|
- `tokenizer`
|
|
- `xml`
|
|
- `ctype`
|
|
- `json`
|
|
- `bcmath`
|
|
- `fileinfo`
|
|
|
|
> Die meisten Shared-Hosting-Anbieter haben alle genannten Erweiterungen bereits aktiviert.
|
|
|
|
### Weitere Voraussetzungen
|
|
|
|
- FTP- oder Dateimanager-Zugang zum Webspace
|
|
- Eine MySQL/MariaDB-Datenbank (wird vom Hoster bereitgestellt)
|
|
- Das Document-Root muss auf einen Unterordner (`/public`) zeigbar sein
|
|
|
|
---
|
|
|
|
## 2. Dateien hochladen
|
|
|
|
1. Laden Sie das aktuelle Schneespur-Release herunter (ZIP-Archiv).
|
|
2. Entpacken Sie das Archiv auf Ihrem Computer.
|
|
3. Laden Sie den gesamten Inhalt per FTP oder Dateimanager in Ihr Webverzeichnis hoch, z. B. `/schneespur/` oder direkt ins Hauptverzeichnis.
|
|
|
|
**Ordnerstruktur nach dem Upload:**
|
|
|
|
```
|
|
/schneespur/
|
|
app/
|
|
bootstrap/
|
|
config/
|
|
database/
|
|
lang/
|
|
public/ <-- hierhin muss das Document-Root zeigen
|
|
resources/
|
|
routes/
|
|
storage/
|
|
vendor/
|
|
.env.example
|
|
artisan
|
|
composer.json
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Document-Root konfigurieren
|
|
|
|
Das Document-Root (manchmal auch „Webroot" oder „Stammverzeichnis" genannt) Ihrer Domain muss auf den Unterordner `public/` zeigen.
|
|
|
|
**Beispiel:** Wenn Sie die Dateien nach `/schneespur/` hochgeladen haben, setzen Sie das Document-Root auf `/schneespur/public/`.
|
|
|
|
So geht das bei gängigen Hostern:
|
|
|
|
- **Strato:** Paket-Verwaltung → Domain-Verwaltung → Umleitung/Ziel → Pfad ändern
|
|
- **IONOS:** Hosting → Domains → Document-Root bearbeiten
|
|
- **All-Inkl:** Domain-Einstellungen → Ordnerzuordnung
|
|
|
|
> **Wichtig:** Wenn Ihr Hoster keinen Unterordner als Document-Root erlaubt, verschieben Sie den Inhalt von `public/` ins Hauptverzeichnis und passen Sie die Pfade in `index.php` entsprechend an. Der Installations-Assistent hilft dabei nicht — kontaktieren Sie im Zweifel Ihren Hoster.
|
|
|
|
---
|
|
|
|
## 4. Datenbank anlegen
|
|
|
|
Erstellen Sie über das Verwaltungspanel Ihres Hosters eine neue MySQL-Datenbank. Notieren Sie sich:
|
|
|
|
- **Host** (z. B. `localhost` oder `rdbms.strato.de`)
|
|
- **Port** (Standard: `3306`)
|
|
- **Datenbankname**
|
|
- **Benutzername**
|
|
- **Passwort**
|
|
|
|
Diese Daten benötigen Sie im nächsten Schritt.
|
|
|
|
---
|
|
|
|
## 5. Installations-Assistent
|
|
|
|
Öffnen Sie Ihre Domain im Browser. Schneespur erkennt automatisch, dass noch keine Installation vorliegt, und startet den Assistenten.
|
|
|
|
### Schritt 1: Willkommen
|
|
|
|
Der Assistent prüft die Grundvoraussetzungen und erzeugt die Konfigurationsdatei (`.env`) sowie den Anwendungsschlüssel (`APP_KEY`).
|
|
|
|
### Schritt 2: Datenbank
|
|
|
|
Geben Sie die Zugangsdaten aus Schritt 4 ein. Der Assistent testet die Verbindung, bevor er fortfährt.
|
|
|
|
> Falls die `.env`-Datei nicht beschreibbar ist (selten bei Shared-Hosting), zeigt der Assistent eine Anleitung zum manuellen Bearbeiten per FTP an.
|
|
|
|
### Schritt 3: Systemcheck
|
|
|
|
Der Assistent prüft PHP-Version, Erweiterungen und Schreibrechte auf wichtige Verzeichnisse (`storage/`, `bootstrap/cache/`). Fehlende Erweiterungen werden als Pflicht oder Empfehlung markiert.
|
|
|
|
### Schritt 4: Datenbank-Migration
|
|
|
|
Die Datenbanktabellen werden automatisch angelegt. Dieser Schritt kann bei Fehlern beliebig oft wiederholt werden, ohne Datenverlust.
|
|
|
|
### Schritt 5: Anwendungskonfiguration
|
|
|
|
Legen Sie fest:
|
|
|
|
- **App-URL** (Ihre Domain, z. B. `https://schneespur.meinefirma.de`)
|
|
- **Zeitzone** (z. B. `Europe/Berlin`)
|
|
- **Sprache** (`de` oder `en`)
|
|
|
|
### Schritt 6: Speicher & Caches
|
|
|
|
Der Assistent erstellt die Verknüpfung zum öffentlichen Speicher (`storage:link`) und baut Caches auf. Falls die Verknüpfung auf Ihrem Hoster nicht funktioniert, wird eine Anleitung zum manuellen Anlegen per FTP angezeigt.
|
|
|
|
### Schritt 7: Admin-Konto
|
|
|
|
Erstellen Sie Ihr Administrator-Konto (Name, E-Mail, Passwort mit mindestens 8 Zeichen).
|
|
|
|
### Schritt 8: E-Mail-Konfiguration (optional)
|
|
|
|
Richten Sie SMTP-Versand ein, damit Schneespur Benachrichtigungen senden kann. Dieser Schritt kann übersprungen und später in den Einstellungen nachgeholt werden.
|
|
|
|
### Fertig
|
|
|
|
Nach Abschluss sehen Sie eine Zusammenfassung. Sie können sich jetzt mit Ihren Admin-Zugangsdaten anmelden.
|
|
|
|
---
|
|
|
|
## 6. Cron-Job einrichten
|
|
|
|
Schneespur benötigt einen Cron-Job, der einmal pro Minute den Laravel-Scheduler ausführt. Dieser verarbeitet die Auftragswarteschlange (z. B. Wetterdaten abrufen, Benachrichtigungen senden).
|
|
|
|
### Cron-Befehl
|
|
|
|
```
|
|
* * * * * /usr/local/bin/php /pfad/zu/schneespur/artisan schedule:run >> /dev/null 2>&1
|
|
```
|
|
|
|
> **Wichtig:** Ersetzen Sie `/pfad/zu/schneespur/` durch den tatsächlichen Pfad auf Ihrem Webspace und `/usr/local/bin/php` durch den PHP-Pfad Ihres Hosters (häufig auch `/usr/bin/php` oder `/usr/bin/php8.3`).
|
|
|
|
### So richten Sie den Cron-Job ein
|
|
|
|
- **Strato:** Paket-Verwaltung → Cron-Jobs → Neuer Cronjob
|
|
- **IONOS:** Hosting → Cron-Jobs → Cronjob anlegen
|
|
- **All-Inkl:** Tools → Cronjobs → Neuer Cronjob
|
|
|
|
Stellen Sie die Ausführung auf **jede Minute** oder das kürzeste verfügbare Intervall.
|
|
|
|
### Warum ist der Cron-Job nötig?
|
|
|
|
Ohne Cron-Job werden keine Hintergrundaufgaben verarbeitet:
|
|
|
|
- Wetterdaten werden nicht automatisch zu Einsätzen hinzugefügt
|
|
- E-Mail-Benachrichtigungen werden nicht versendet
|
|
- Geplante Aufgaben laufen nicht
|
|
|
|
---
|
|
|
|
## 7. OwnTracks einrichten
|
|
|
|
OwnTracks ist die GPS-Tracking-App, mit der Ihre Fahrer die Einsätze aufzeichnen. Jeder Fahrer benötigt die App auf seinem Smartphone.
|
|
|
|
### Kurzanleitung
|
|
|
|
1. **App installieren:** OwnTracks aus dem App Store (iOS) oder Google Play Store (Android) herunterladen.
|
|
2. **Zugangsdaten erzeugen:** Melden Sie sich als Admin in Schneespur an, öffnen Sie die Fahrer-Übersicht und klicken Sie beim jeweiligen Fahrer auf „Zugangsdaten". Schneespur erzeugt automatisch Benutzername und Passwort.
|
|
3. **QR-Code scannen:** Auf der Zugangsdaten-Seite wird ein QR-Code angezeigt. Der Fahrer scannt diesen mit der OwnTracks-App, und die Verbindung wird automatisch konfiguriert.
|
|
4. **Manuell konfigurieren** (falls QR-Code nicht funktioniert):
|
|
- Modus: **HTTP**
|
|
- URL: `https://ihre-domain.de/api/owntracks/report`
|
|
- Benutzername und Passwort: wie in Schneespur angezeigt
|
|
5. **Testen:** Öffnen Sie in Schneespur unter „OwnTracks" die Übersicht. Sobald der Fahrer die App startet, sollte dort ein grüner Status erscheinen.
|
|
|
|
---
|
|
|
|
## 8. Update-Anleitung
|
|
|
|
### Vor dem Update
|
|
|
|
1. Erstellen Sie ein Backup (siehe [Backup](#9-backup)).
|
|
2. Aktivieren Sie den Wartungsmodus: Öffnen Sie `https://ihre-domain.de/down` im Browser oder führen Sie `php artisan down` per SSH/Cron aus.
|
|
|
|
### Update durchführen
|
|
|
|
1. Laden Sie das neue Release herunter.
|
|
2. Überschreiben Sie alle Dateien per FTP. Überspringen Sie dabei **nicht** die `.env`-Datei — diese wird beim Upload ohnehin nicht überschrieben, solange Sie nur die Release-Dateien hochladen.
|
|
3. Führen Sie die Datenbank-Migration aus. Dafür gibt es zwei Wege:
|
|
- **Ueber den Browser:** Öffnen Sie `https://ihre-domain.de/admin/settings` und prüfen Sie, ob eine Update-Migration angeboten wird.
|
|
- **Per Cron/SSH:** `php artisan migrate --force`
|
|
4. Leeren Sie die Caches: `php artisan config:cache && php artisan view:cache`
|
|
5. Deaktivieren Sie den Wartungsmodus: Öffnen Sie `https://ihre-domain.de/up` oder führen Sie `php artisan up` aus.
|
|
|
|
---
|
|
|
|
## 9. Backup
|
|
|
|
### Was sichern?
|
|
|
|
| Was | Wo | Wie |
|
|
|-----|----|----|
|
|
| Datenbank | MySQL-Datenbank | phpMyAdmin → Export (SQL-Format) |
|
|
| Hochgeladene Dateien | `storage/app/` | Per FTP herunterladen |
|
|
| Konfiguration | `.env`-Datei im Hauptverzeichnis | Per FTP herunterladen |
|
|
|
|
### Empfohlener Rhythmus
|
|
|
|
- **Datenbank:** wöchentlich oder vor jedem Update
|
|
- **Dateien:** vor jedem Update
|
|
- **Konfiguration:** nach jeder Änderung und vor Updates
|
|
|
|
---
|
|
|
|
## 10. Troubleshooting
|
|
|
|
### Installations-Assistent erscheint nicht
|
|
|
|
- Prüfen Sie, ob das Document-Root korrekt auf `/public` zeigt.
|
|
- Prüfen Sie, ob die `.htaccess`-Datei im `public/`-Ordner vorhanden ist.
|
|
- Stellen Sie sicher, dass `mod_rewrite` (Apache) aktiviert ist.
|
|
|
|
### Datenbankverbindung schlägt fehl
|
|
|
|
- Prüfen Sie Host, Port, Datenbankname, Benutzername und Passwort.
|
|
- Bei Strato lautet der Host oft `rdbms.strato.de`, nicht `localhost`.
|
|
- Stellen Sie sicher, dass der Datenbankbenutzer Zugriff auf die angegebene Datenbank hat.
|
|
|
|
### Seite zeigt „500 Internal Server Error"
|
|
|
|
- Prüfen Sie die Schreibrechte: `storage/` und `bootstrap/cache/` müssen beschreibbar sein (Rechte 755 oder 775).
|
|
- Schauen Sie in `storage/logs/laravel.log` nach der Fehlermeldung.
|
|
|
|
### GPS-Daten kommen nicht an
|
|
|
|
- Prüfen Sie in OwnTracks, ob der Modus auf „HTTP" steht (nicht MQTT).
|
|
- Prüfen Sie die URL: `https://ihre-domain.de/api/owntracks/report`
|
|
- Prüfen Sie Benutzername und Passwort in der OwnTracks-App.
|
|
- Öffnen Sie die OwnTracks-Übersicht in Schneespur — dort wird der letzte Verbindungsstatus angezeigt.
|
|
|
|
### Wetterdaten fehlen bei Einsätzen
|
|
|
|
- Stellen Sie sicher, dass der Cron-Job läuft (siehe [Cron-Job einrichten](#6-cron-job-einrichten)).
|
|
- Wetterdaten werden über Open-Meteo abgerufen. Prüfen Sie, ob Ihr Server ausgehende HTTPS-Verbindungen erlaubt.
|
|
|
|
### E-Mails werden nicht versendet
|
|
|
|
- Prüfen Sie die SMTP-Einstellungen unter Einstellungen → E-Mail.
|
|
- Nutzen Sie die Test-E-Mail-Funktion in den Einstellungen.
|
|
- Schauen Sie in `storage/logs/laravel.log` nach Fehlermeldungen.
|
|
|
|
### Cron-Job funktioniert nicht
|
|
|
|
- Prüfen Sie den PHP-Pfad: Führen Sie `which php` aus oder fragen Sie Ihren Hoster.
|
|
- Prüfen Sie den Pfad zur `artisan`-Datei.
|
|
- Testen Sie den Befehl manuell: `php /pfad/zu/schneespur/artisan schedule:run`
|
|
|
|
---
|
|
|
|
## Hilfe
|
|
|
|
Bei Fragen nutzen Sie die integrierte Hilfe im Admin-Bereich (Menü → Hilfe) oder erstellen Sie ein Issue im GitHub-Repository.
|