addet test set

UPLOAD.md

@@ -1,91 +1,129 @@
-# Projektdateien auf einen Raspberry Pi kopieren
+# Versionierte Updates auf dem Raspberry Pi
 
-Das Skript `tools/upload_to_pi.sh` kopiert den gewählten lokalen Ordner per
-SSH und `rsync` auf **einen** Pi. Ohne `--source` ist das Projektverzeichnis
-die Quelle. Es löscht keine Dateien auf dem Pi. Benutzer, Host und absoluter
-Zielpfad werden beim Aufruf angegeben. Der Nutzer-Screenshot vom 14. Oktober
-2026 zeigt einen erfolgreichen SSH-Login als `marcinator_2` auf
-`raspi5wlan.local` und Projektdateien unter `~/halloween`.
+`tools/upload_to_pi.sh` überträgt per SSH/rsync eine neue Version und richtet
+bei jedem angewendeten Update den systemd-Autostart der WebUI ein. Ohne
+`--apply` zeigt es nur eine lokale Vorschau und verbindet sich nicht zum Pi.
+
+## Auf dem Laptop ausführen
+
+Das folgende Beispiel verwendet den vom Nutzer bestätigten SSH-Benutzer,
+Hostnamen und Projektordner. Der absolute Home-Pfad muss auf dem Pi stimmen:
+
+```bash
+bash tools/upload_to_pi.sh --user marcinator_2 --host raspi5wlan.local \
+  --remote-dir /home/marcinator_2/halloween --web-host 0.0.0.0
+```
+
+Zum tatsächlichen Update denselben Befehl mit `--apply` ausführen:
+
+```bash
+bash tools/upload_to_pi.sh --user marcinator_2 --host raspi5wlan.local \
+  --remote-dir /home/marcinator_2/halloween --web-host 0.0.0.0 --apply
+```
+
+`--web-host 0.0.0.0` ermöglicht den gewünschten Heimnetzzugriff auf
+`http://raspi5wlan.local:8000`. Die WebUI hat noch keinen Login; keine
+Router-Portfreigabe einrichten. Mit `--web-host 127.0.0.1` stattdessen den
+SSH-Tunnel aus `SOFTWARE.md` verwenden. Ohne Angabe bleibt die gespeicherte
+Wahl erhalten; beim ersten Update gilt Loopback. `--install-service` wird
+weiterhin akzeptiert, ist aber nicht mehr erforderlich.
+
+Autostart heißt: Der Webdienst startet beim Hochfahren des Pi. Ein Browser
+auf dem Laptop wird dadurch nicht automatisch geöffnet.
 
 ## Voraussetzungen
 
-- Auf dem Laptop: `ssh` und `rsync`.
-- Auf dem Pi: aktivierter SSH-Zugang und `rsync`.
-- Der Benutzer muss im Zielpfad schreiben dürfen.
-- Für den optionalen Autostart: Pi-Software laut `SOFTWARE.md` vorbereiten,
-  insbesondere `.venv` im Zielordner; `sudo` muss auf dem Pi nutzbar sein.
-- Vor dem ersten Upload den Pi per `ssh BENUTZER@HOST` erreichen und den
-  angezeigten Hostschlüssel anhand des eigenen Geräts prüfen. Bei einem
-  geänderten Hostschlüssel die Ursache klären, nicht die Prüfung abschalten.
+- Laptop: `bash`, `python3`, `ssh`, `rsync`.
+- Pi: `bash`, `rsync`, `flock`, `runuser` (util-linux), `python3-venv`,
+  `python3-picamera2`, systemd
+  und nutzbares `sudo` für den normalen SSH-Benutzer.
+- Der Pi muss die Python-Pakete aus `requirements.txt` herunterladen können.
+  Pro Version wird eine eigene `.venv` mit Systempaketzugriff angelegt;
+  pip verwendet ausschließlich Wheels, keinen impliziten Quellbuild.
+- Genug Speicher für neue Version, Python-Umgebung und vollständige Sicherung
+  von `data/`. Alte Versionen und Sicherungen werden nicht automatisch gelöscht.
+- SSH-Hostschlüssel am eigenen Gerät prüfen; die Prüfung bleibt eingeschaltet.
+- Eine mit Uvicorn manuell gestartete WebUI vor dem ersten Update mit `Strg+C`
+  beenden. Ein bestehender, vom Projekt verwalteter Dienst wird selbst gestoppt.
+  Eine fremde gleichnamige systemd-Unit wird abgelehnt.
 
-## Ablauf
+## Einmalige sudo-Abfrage beim Update
 
-`BENUTZER`, `HOST` und `ZIEL` durch die geprüften Werte ersetzen. `ZIEL`
-muss ein absoluter Pfad ohne Leerzeichen sein.
+Das Uploadskript bereitet die neue Python-Umgebung als normaler Pi-Benutzer vor.
+Danach läuft die Umschaltung mit **einem einzigen sudo-Aufruf**: Unitprüfung,
+Dienststopp, Sicherung, Versionswechsel, Dienstneustart und gegebenenfalls Rückfall.
+Bei gültiger sudo-Anmeldung entfällt die Frage; sonst ist für diesen Aufruf eine
+Anmeldung nötig. Keine weitere Abfrage während Neustart oder Rückfall, auch bei
+kurzem oder deaktiviertem sudo-Zeitstempel. SSH-Anmeldung ist davon getrennt.
+
+Passwörter werden vom Skript weder gelesen noch gespeichert. Keine sudoers-
+Ausnahme, kein Passwort per Kommandozeile/Pipe und keine Änderung der sudo-Frist.
+Abhängigkeiten und Python-Prüfungen bleiben unprivilegiert; der privilegierte
+Teil startet Python und den Unit-Renderer mit `runuser` als ursprünglichem
+Pi-Benutzer. Auch der Webdienst behält diesen Benutzer. Die Updatesperre bleibt
+im wartenden unprivilegierten Elternprozess über den ganzen sudo-Aufruf gehalten.
+Eine abgelehnte sudo-Anmeldung lässt den aktiven Dienst und Datenbestand bestehen.
+
+## Ablauf und Verzeichnisstruktur
+
+1. Neue Dateien unter `releases/ZEITSTEMPEL-ZUFALL/` übertragen.
+2. Mit einer Updatesperre parallele Aktivierung verhindern; neue Python-Umgebung
+   vorbereiten und Importe/Syntax prüfen, während die alte Version weiterläuft.
+3. Dienst stoppen; Daten einschließlich SQLite-Dateien und Einstellungen unter
+   `backups/VERSION/data/` sichern. Keine laufende Datenbank kopieren.
+4. `current` atomar auf die neue Version umschalten und die Unit aktualisieren.
+   `HALLOWEEN_STATE_DIR` verweist immer auf den gemeinsamen Basisordner `data/`.
+5. Autostart aktivieren, Dienst neu starten, `/api/status` bis zu 30 Versuche
+   mit je einer Sekunde Pause abfragen und aktiven Dienststatus prüfen.
+6. Bei einem Fehler während der Umschaltung Dienst stoppen, vorherige Version,
+   Daten und Unit wiederherstellen und den alten Dienst samt HTTP-Antwort prüfen.
+   Änderungen des fehlgeschlagenen Starts bleiben in `backups/VERSION/failed-data/`.
+
+Die bisherige flache Installation mit `run.py` und `.venv` im Basisordner
+bleibt beim ersten Update als Rückfallziel bestehen. Ohne vorherige Installation
+kann ein fehlgeschlagener Erststart nur die Daten und den Zustand ohne neuen
+Dienst wiederherstellen. Ein Fehlschlag liefert einen Fehlerstatus, auch wenn
+der Rückfall gelungen ist. Ein unvollständiger Rückfall wird ausdrücklich gemeldet.
+Abrupter Stromverlust/SIGKILL während des Updates ist nicht automatisch abgedeckt.
+
+`data/` wird niemals vom Laptop übertragen: Datenbank, Bilder, Modelle,
+Modus und Erkennungseinstellungen bleiben auf dem Pi. `.git`, `.venv`,
+Vorschauen, Referenzen, `.env`, Schlüssel, Versionsordner und Sicherungen werden
+ebenfalls ausgeschlossen. Eigene Dateien außerhalb von `data/` bleiben im
+Basisordner, werden aber nicht automatisch in die neue Version übernommen.
+Das Skript löscht keine alten Pi-Dateien. Systempakete werden nicht geändert.
+Nach Start gelten die bisherigen Freigabe-/Resetbedingungen der Effektsteuerung.
+
+## Auf dem Pi prüfen
 
 ```bash
-BENUTZER='BENUTZER'
-HOST='HOST'
-ZIEL='/home/BENUTZER/halloween'
-
-bash tools/upload_to_pi.sh --user "$BENUTZER" --host "$HOST" --remote-dir "$ZIEL"
-bash tools/upload_to_pi.sh --user "$BENUTZER" --host "$HOST" --remote-dir "$ZIEL" --apply
+systemctl status halloween-grab.service
+systemctl is-enabled halloween-grab.service
+readlink -f ~/halloween/current
+sudo journalctl -u halloween-grab.service -n 80 --no-pager
 ```
 
-Der erste Aufruf zeigt nur die geplanten Befehle. Der zweite legt den
-Zielordner an und überträgt die Dateien. Ein anderer Quellordner kann mit
-`--source /absoluter/pfad` angegeben werden. Anschließend auf dem Pi prüfen:
+Erkennung nach dem ersten Update bei Bedarf im aktiven Versionsordner einrichten:
 
 ```bash
-ssh "$BENUTZER@$HOST" "ls -la '$ZIEL'"
-```
-
-Soll die WebUI auf dem Pi nach jedem Neustart automatisch laufen, beim
-Upload `--install-service` ergänzen:
-
-```bash
-bash tools/upload_to_pi.sh --user "$BENUTZER" --host "$HOST" --remote-dir "$ZIEL" --install-service
-bash tools/upload_to_pi.sh --user "$BENUTZER" --host "$HOST" --remote-dir "$ZIEL" --install-service --apply
-```
-
-Der erste Befehl ist wieder nur eine lokale Vorschau. Der zweite überträgt
-die Dateien, installiert/aktualisiert die systemd-Unit mit `sudo` auf dem Pi
-und startet den Dienst. Bei späteren Updates startet der Dienst so mit dem
-neuen Code neu. Er bindet weiterhin nur an `127.0.0.1` des Pi; vom Laptop
-aus ist der SSH-Tunnel aus `SOFTWARE.md` nötig. Es öffnet sich kein
-Browserfenster von selbst.
-
-Das Skript lässt `.git`, `.venv`, `data`, `preview`, `references`,
-`__pycache__`, `.env` und übliche Schlüsseldateien aus. So bleiben
-Laufzeiteinstellungen auf dem Pi und die großen Konzeptdateien lokal.
-Es synchronisiert vorhandene Dateien, löscht aber
-keine alten Dateien auf dem Pi. Zugangsdaten und andere Geheimnisse gehören
-nicht in den Quellordner. Für zwei Pis den Upload mit den jeweils geprüften
-Zielwerten separat ausführen.
-
-## Bestätigter Stand
-
-Der Nutzer-Screenshot vom 14. Oktober 2026 bestätigt SSH-Zugang und vorhandene
-Projektdateien auf dem Pi: unter anderem `run.py`, `halloween/`, `tools/`,
-`tests/` und die Requirements-Dateien. Zeitpunkt und Methode der bisherigen
-Übertragung sowie die Übereinstimmung mit dem aktuellen lokalen Stand sind
-offen. Installation der Python-Pakete, WebUI-Start, Kamera, SSH-Tunnel und
-systemd-Autostart sind damit noch nicht bestätigt.
-
-## Personenerkennung nach dem Upload einrichten
-
-Die Modellgewichte und Erkennungseinstellungen liegen unter `data/` und bleiben
-beim Upload erhalten. Bei der ersten Einrichtung nach Code-Übertragung auf dem
-Pi die zusätzlichen Pakete und das geprüfte Modell ausdrücklich installieren:
-
-```bash
-cd ~/halloween
+cd ~/halloween/current
 sudo apt update
 sudo apt install python3-opencv python3-numpy
-python3 -m venv --system-site-packages .venv
-.venv/bin/python -c "import cv2, numpy; print(cv2.__version__, cv2.__file__); print(numpy.__version__)"
-.venv/bin/python tools/install_detection_model.py
+HALLOWEEN_STATE_DIR=/home/marcinator_2/halloween/data \
+  .venv/bin/python tools/install_detection_model.py
+sudo systemctl restart halloween-grab.service
 ```
 
-Danach den Server neu starten und Linie, Richtung, Bereich und Aktivierung in
-der WebUI speichern. Details und Fehlerbehandlung in `SOFTWARE.md`.
+OpenCV mindestens 4.10 und das echte Kamera-/Erkennungsverhalten gemäß
+`SOFTWARE.md` prüfen. Nachfolgende Versionsumgebungen nutzen dieselben Pi-Systempakete.
+
+## Verifizierter Stand
+
+Lokale Tests simulieren Python-Installation, systemd und HTTP-Prüfung und prüfen
+Versionswechsel, Autostart-Unit, Datenbestand, Start-/HTTP-Fehler, Rückfall,
+Erstinstallation, Altinstallation und Ablehnung fremder Units/manueller Server.
+Sie bestätigen keine echte Pi-Installation, Kamera oder Neustartfestigkeit.
+Der Nutzer hat das echte Livebild und anschließend den erfolgreichen
+Updateaufruf bestätigt. Autostart nach einem tatsächlichen Pi-Neustart und
+automatischer Rückfall bei einem Fehler sind noch am Gerät zu prüfen.
+Die HTTP-Prüfung bestätigt die Status-API, nicht Bildqualität oder Aktoren.