domandClaude Opus 5.5 cb2566a537 Accept icu_cameratrap_rep as camera trap image event type
ICU sends "icu_cameratrap_rep" instead of the documented Gundi/EarthRanger
type "cameratrap_rep". Events of the unknown type were stored as IGNORED, so
the following attachment upload got 404 and no image was ingested. Treat both
names as image events.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 15:55:37 +02:00
2026-02-06 15:31:21 +00:00
2026-02-06 11:44:32 +01:00
2026-02-06 14:05:27 +00:00

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

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):

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)

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

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/<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.

S
Description
ICU images are beeing processed and stored in the meles universe with this
Readme
194 KiB
Languages
Python 98.3%
Dockerfile 1.7%