Files
melesICUmover/README.md
T
domandClaude Opus 5 2fc8dea10c Add Gundi v2 push receiver for ICU and normalized data model
ICU now pushes camera events via a Gundi-v2-compatible API instead of
dropping file triplets into S3. The new gundi-receiver service accepts
them directly, so images are in the system within seconds instead of
waiting out the 90s age gate + poll interval. OCR of the burnt-in camera
timestamp stays mandatory (ICU only sends server times; OCR detects
drifting camera clocks) but now runs asynchronously after ingest.

The push path writes a normalized model that separates what the legacy
metadata table conflates: camera_status (status time series), image
(image properties) and detection (classifications), plus the
image_with_status view as the portal's migration target. A repeatable,
batched migration splits existing metadata/category rows into it.

The legacy poller is unchanged and keeps writing metadata/category until
the portal is switched over.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-18 13:54:21 +00:00

4.6 KiB

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)

cp .env.example .env      # danach echte, rotierte Werte eintragen
chmod 600 .env
docker compose up -d --build
docker compose logs -f

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 (JSON, Objekt oder Liste)
POST /v2/events/<object_id>/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.

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:

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

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:

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 fuer Secret-Rotation, Umzug auf einen neuen Server und Stilllegung des Altservers.