schneespur/release/schneespur-1.0.2/INSTALL.de.md

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
2. Dateien hochladen
3. Document-Root konfigurieren
4. Datenbank anlegen
5. Installations-Assistent
6. Cron-Job einrichten
7. OwnTracks einrichten
8. Update-Anleitung
9. Backup
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).
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).
• 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.