# melesICUmover Dauer-Poller, der Wildkamera-Bilder aus einem Hetzner-S3-Bucket verarbeitet: liest neue Bilder + `metadata.json` (+ optional `_categories.json`), extrahiert per **OCR** (Tesseract) den Overlay-Zeitstempel, schreibt **EXIF**-Daten (exiftool), legt verarbeitetes Bild + Thumbnail zurueck nach S3, persistiert alles nach **PostgreSQL** (`remote_cam.*`), pusht optional an die **DeerMapper-API** und raeumt den Entrance-Ordner auf. Zustand pro Bild in `remote_cam.import_job.status`. ## Konfiguration Zweigeteilt - bewusst: | Datei | Inhalt | Im Git? | |-------|--------|---------| | `config.yaml` | Nicht-geheime App-Tunables + oeffentliche Endpunkte | **ja** (Template) | | `.env` | Secrets: S3-Keys, `PG_DSN`, API-Key | **nein** (`.gitignore`) | Secrets werden **ausschliesslich** ueber Umgebungsvariablen geladen; die Werte in `.env` ueberschreiben bzw. ergaenzen `config.yaml`. Beim Start prueft die App die Vollstaendigkeit und bricht mit klarer Meldung ab, falls ein Secret fehlt. Unterstuetzte Umgebungsvariablen: `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `PG_DSN`, `DEERMAPPER_API_URL`, `DEERMAPPER_API_KEY`, `GUNDI_API_KEY`, `CONFIG_YAML`, `DEBUG`. ## Betrieb (Docker) ```bash cp .env.example .env # danach echte, rotierte Werte eintragen chmod 600 .env docker compose up -d --build docker compose logs -f ``` ### Stoerungen und Lebenszeichen (Poller) Fehler eines Zyklus (S3 5xx/Throttling, Netz, DB weg) beenden den Poller nicht: er loggt eine Zeile `[CYCLE_FAIL] kind=transient ...` und versucht es mit exponentiellem Backoff erneut (`backoff_initial_seconds` bis `backoff_max_seconds`, Reset nach Erfolg, dann `[RECOVERED]`). Unerwartete Fehler (`kind=unexpected`, z. B. AccessDenied oder Programmierfehler) werden zusaetzlich mit Traceback geloggt. Ein Bild, bei dem S3/DB wegbricht, bleibt wie bisher auf `ERROR`; der Rest des Batches wartet auf den naechsten Zyklus. Alle `heartbeat_seconds` erscheint `[HEARTBEAT]` mit Zaehlern (Zyklen, Bilder, Fehler, letzter Erfolg). Der Docker-Healthcheck prueft, ob die Hauptschleife vorankommt (`/tmp/melesicumover.heartbeat` juenger als 15 min): ```bash docker inspect -f '{{.State.Health.Status}} restarts={{.RestartCount}}' melesicumover docker exec melesicumover cat /tmp/melesicumover.heartbeat ``` S3-Timeouts/-Retries stehen unter `app.s3_*` in `config.yaml`. ### Eingang pruefen (verwaiste Objekte) ```bash docker compose run --rm --no-deps melesicumover python -m tools.entrance_inventory --db ``` Listet `icu/entrance/` nach Typ (vollstaendig, JPG ohne JSON, JSON ohne JPG, nur Kategorien, fremd) und Alter, optional mit `import_job`-Status. Nur lesend. ### Tests ```bash pip install -r requirements.txt python -m unittest discover -s tests -v # oder: python -m pytest tests ``` Simulierte S3-/DB-Stoerungen fuer Backoff und Fehlerbehandlung; weder Netz noch DB noetig. ## Gundi-Push-Pfad (`gundi-receiver`) ICU pusht Events ueber eine Gundi-v2-kompatible API. Der Service `gundi-receiver` (gleiches Image, `gundi_receiver.py`) nimmt sie entgegen: | Route | Zweck | |-------|-------| | `POST /v2/events/` | `camera_status_report` oder `cameratrap_rep` / `icu_cameratrap_rep` (JSON, Objekt oder Liste) | | `POST /v2/events//attachments/` | JPEG zum `cameratrap_rep` (multipart/form-data) | | `GET /healthz` | Healthcheck | Auth ueber den Header `apikey` = `GUNDI_API_KEY` aus der `.env`. Ablauf: Event und JPEG werden durable abgelegt und sofort quittiert. Stufe 1 (Sekunden) schreibt processed-JPEG + Thumbnail und `image` + `detection`. Stufe 2 liest danach asynchron per OCR den Kamera-Zeitstempel, setzt `image.ocr_ts` und `DateTimeOriginal`. Ein Sweep holt haengengebliebene Schritte nach und markiert Events ohne Bild nach `abandon_after_hours` als `ABANDONED`. ### Verhalten bei S3-/DB-Ausfall | Teil | Verhalten | |------|-----------| | Status-Events, Event anlegen | brauchen kein S3; bei DB-Ausfall `503` + `Retry-After: 30` | | Bild-Upload (`.../attachments/`) | S3-Zugriff mit kurzen Zeitlimits (`gundi.upload_*`: 5 s Connect, 30 s Read, 2 Versuche), ohne offene DB-Sperre. Bei S3-Stoerung `503` + `Retry-After: 30`; das Event bleibt bis `abandon_after_hours` auf `AWAITING_ATTACHMENT`, der Client kann wiederholen | | Ingest/OCR im Hintergrund | S3-/DB-Stoerungen (`main.is_transient_error`) zaehlen **nicht** gegen `max_attempts`; der Sweep wiederholt alle `stale_after_seconds`. Nur echte Datenfehler fuehren zu `FAILED`/`FAIL` | | Sweep | reiht dieselbe ID nicht doppelt ein (kein Stau bei langem Ausfall) | | Alarm | `[GUNDI][ALARM] backlog ...` im Log (hoechstens alle 5 min), wenn Eintraege laenger als `gundi.alarm_after_seconds` in `RECEIVED`/`AWAITING_ATTACHMENT`/OCR-`PENDING` haengen oder in den letzten 24 h neue `FAILED`/`FAIL` entstanden sind (aeltere loesen keinen Dauer-Alarm aus) | Gescheiterte Eintraege zuruecksetzen (Trockenlauf ohne `--apply`): ```bash docker exec -w /app melesicumover-gundi python -m tools.gundi_requeue --apply ``` Wichtig: Der Client (ICU) muss nach `5xx`/Timeout den Upload wiederholen; ohne Wiederholung geht das Bild verloren, wenn S3 laenger ausfaellt. ### Datenmodell (`schema/001_domain_model.sql`) | Tabelle | Inhalt | |---------|--------| | `remote_cam.camera_status` | Statusupdates / Kameraeigenschaften (Zeitreihe je IMEI) | | `remote_cam.image` | Bildeigenschaften inkl. `servertime`, `ocr_ts`, `ocr_state` | | `remote_cam.detection` | Objektklassifikationen, `confidence` 0..1 | | `remote_cam.image_with_status` | View: Bild + zum `servertime` gueltiger Status | | `remote_cam.gundi_inbox` | Transportschicht: Rohevents + Zustand des Push-Pfads | Das Schema legt der Receiver beim Start an. Die Legacy-Tabellen `metadata` / `category` werden vom alten Poller weiter befuellt, bis das Portal umgestellt ist. ### Bestandsdaten migrieren Split `metadata` -> `image` + `camera_status`, `category` -> `detection`. Wiederholbar, batchweise, liest die Alttabellen nur: ```bash docker compose run --rm --no-deps gundi-receiver python -m tools.migrate_legacy ``` Vor dem Portal-Cutover erneut ausfuehren, um zwischenzeitlich neue Bilder nachzuziehen. `--verify-only` prueft nur die Zaehlungen. ### Test ```bash docker compose up -d --build gundi-receiver docker compose run --rm --no-deps gundi-receiver \ python -m tools.gundi_smoke_test --url http://127.0.0.1:8090 --jpeg /pfad/zu/bild.jpg ``` Standardmaessig schreibt der Pfad unter `icu/gundi-test/` (siehe `gundi:` in `config.yaml`); fuer den Produktivbetrieb `processed_prefix` / `thumb_prefix` auf `icu/processed/` / `icu/thumbnails/` umstellen. ### nginx (`icu.meles.eu`) vhost liegt unter [`deploy/nginx/icu.meles.eu`](deploy/nginx/icu.meles.eu): ```bash sudo cp deploy/nginx/icu.meles.eu /etc/nginx/sites-available/ sudo ln -s /etc/nginx/sites-available/icu.meles.eu /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx sudo certbot --nginx -d icu.meles.eu --redirect ``` ICU-Endpunkt: `https://icu.meles.eu/v2/events/` (immer https — der 80->443-Redirect ist ein 301 und wuerde POST in GET verwandeln). ## Sicherheitshinweise - **Niemals** Secrets in `config.yaml` oder ins Git schreiben - nur in `.env`. - `PG_DSN` mit `?sslmode=require`; die Datenbank sollte **nicht** oeffentlich erreichbar sein (privates Netz / Firewall / SSH-Tunnel). - Debug-Port (`5678`) ist standardmaessig aus; bei Bedarf nur an `127.0.0.1` binden. - Nach Kompromittierung (z.B. Secrets waren im Git): **rotieren**, nicht nur entfernen. Siehe [`MIGRATION.md`](MIGRATION.md) fuer Secret-Rotation, Umzug auf einen neuen Server und Stilllegung des Altservers.