No description
  • Python 87.9%
  • Svelte 5.4%
  • HTML 3.2%
  • TypeScript 2.4%
  • CSS 0.8%
  • Other 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
vibe 4d1d7e41bc
Some checks failed
Verify / python (push) Has been cancelled
Verify / browser (push) Has been cancelled
Verify / container (push) Has been cancelled
Publish verified Forgejo image reference and registry deployment instructions
2026-10-09 08:42:43 +02:00
.github/workflows feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
benchmarks Add comprehensive test suite for photo_manager module 2026-10-07 20:57:24 +02:00
config feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
datasets/reference-v1 Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
docs Publish verified Forgejo image reference and registry deployment instructions 2026-10-09 08:42:43 +02:00
frontend Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
scripts Publish verified Forgejo image reference and registry deployment instructions 2026-10-09 08:42:43 +02:00
src feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
tests feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
.dockerignore Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
.env.example feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
.gitignore Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
AGENTS.md Plan portable deployments, resource budgets and selectable ML profiles 2026-10-09 07:48:41 +02:00
BETA_READINESS.md Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
compose.ml.yaml Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
compose.omv.registry.yaml Publish verified Forgejo image reference and registry deployment instructions 2026-10-09 08:42:43 +02:00
compose.omv.yaml feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
compose.source-write.yaml Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
compose.yaml feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
Dockerfile feat: Implement environment-only configuration for OMV Compose plugin 2026-10-08 20:18:39 +02:00
Dockerfile.ml Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
facet-integration-plan.md Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
pyproject.toml Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00
README.md Publish verified Forgejo image reference and registry deployment instructions 2026-10-09 08:42:43 +02:00
requirements.txt Add comprehensive test suite for photo_manager module 2026-10-07 20:57:24 +02:00
setup_facet.py Refactor code structure for improved readability and maintainability 2026-10-04 20:52:25 +02:00
setup_facet_install.py Refactor code structure for improved readability and maintainability 2026-10-04 20:52:25 +02:00
uv.lock Add smoke tests and reference dataset management scripts 2026-10-08 13:53:07 +02:00

Family Photo Manager Beta

Family Photo Manager bereitet große Familien-Fotoarchive für Immich, PhotoPrism und andere Fotoverwaltungen vor. Bestehende Ordner lassen sich erfassen, Duplikate prüfen, Bilder bewerten und konkrete Dateiaktionen nachvollziehbar planen. Die WebUI ist der bevorzugte Bedienweg; eine CLI bleibt für Administration und Automatisierung verfügbar.

Aktuelle Beta: 0.4.0b1 (Docker-Tag 0.4.0-beta.1). Ein früherer Stand wurde mit etwa 17.000 Fotos erprobt. Das ist kein Nachweis für beliebige Archive mit 500.000 Dateien oder jedes NAS-Dateisystem. Aktuelle Prüfergebnisse und nach Schwere geordnete Grenzen stehen in BETA_READINESS.md.

Was die Beta kann

  • Read-only Inventar mit vollständigem BLAKE3, ExifTool-Metadaten und wiederholbaren, inkrementellen Scans; Unterbrechungen markieren nicht erreichte Dateien nicht als fehlend.
  • Familien und Quellen, exakte Duplikate, optionale dHash/pHash-Ähnlichkeit, RAW/JPEG-/Sidecar-Beziehungen, Lightroom-Schutz und Datumsprobleme.
  • Webprüfung mit Vorschauen, menschlichen Sternen, konkreter/festgeschriebener Auswahl, getrennten Analyseergebnissen und persistenten Aufträgen.
  • Gespeicherte Pläne, Dry-run, verifizierte Kopien, separat freigegebene Moves und geprüfte Löschlisten. Export der Dateiaktionen als JSONL-Manifest.
  • Optionale technische Bewertung und ausdrücklich konfigurierte lokale Modelle für Gesichter/Ästhetik. Familienvorschläge benötigen bestätigte Personen und eine Benutzerentscheidung; sie ändern keine Quellenzugehörigkeit.

Nicht enthalten: dauerhafte Galerie, Foto-Backup, Metadateneditor, automatische Foto-Reparatur, Modelltraining oder mitgelieferte Modellgewichte. Ein direkter Upload/Import in Immich oder PhotoPrism ist nicht implementiert. Geschlossene Augen, semantische Suche und eine allgemeine „bestes Serienbild“-Auswahl sind keine zugesicherten Betafunktionen. Der vorhandene Immich-ML-Adapter ist experimentell und auf Immich 3.3.0 festgelegt. Gesichts-/CLIP-Inferenz wurde mit einem echten GPU-Dienst geprüft; Testbericht.

Schutz der Originale

Für wertvolle Fotos ist weiterhin ein separates, geprüftes Backup erforderlich. Beginne mit einer unabhängigen Testdatenbank und einem kleinen Testbestand. Quellen sind im Standard-Compose read-only. Alle Dateiaktionsfreigaben sind aus. Ein Score, Ähnlichkeit oder eine Auswahl führt niemals selbst zu einer Löschung.

Moves entfernen Quellen erst nach vollständiger BLAKE3-Prüfung und dauerhafter Zielveröffentlichung der übertragenen Gruppe. Unbekannte Ziele werden nicht überschrieben. Jeder Ausführungsversuch braucht einen frischen Dry-run und eine Bestätigung. Ein Journal dokumentiert die Operation; Löschen hat keinen Undo. Während freigegebener Dateiaktionen dürfen keine anderen Programme die beteiligten Quellen/Ziele verändern. POSIX-Sperren koordinieren unsere Prozesse, nicht externe Editoren, SMB-Clients oder Sync-Werkzeuge.

Docker starten — neue Testinstallation

Für die Bedienung über die OMV-Weboberfläche: OMV-Compose-Plugin. Die eigenständige compose.omv.yaml verwendet Environment-Variablen für LAN-Zugriff, Ersteinrichtung und Kopierfreigabe; keine TOML-Datei erforderlich. compose.omv.registry.yaml bezieht das geprüfte AMD64-Image aus git.maxbuelk.de/vibe/photo-manager:0.4.0-beta.1-omv (Pull → Up im Plugin). Die manuelle OMV-Testanleitung bleibt als Alternative verfügbar.

Benötigt werden Docker Engine und Compose v2-kompatible CLI auf einem Linux-Host. Intel-/AMD-Systeme einschließlich Ryzen 3200G verwenden linux/amd64. Node und uv werden auf dem NAS nicht benötigt; das Image baut die WebUI in einer eigenen Stufe. Das geprüfte Beta-Image ist in der Forgejo-Registry verfügbar; Zugang und Digest sind in der OMV-Anleitung beschrieben. Alternativ lokal bauen oder ein geprüftes Image über docker load übernehmen.

Im ausgecheckten Repository:

test -e .env || cp .env.example .env

In .env echte vorhandene Hostpfade eintragen:

FPM_IMAGE=family-photo-manager:0.4.0-beta.1
FPM_SOURCE=/srv/fotos/testarchiv
FPM_OUTPUT=/srv/foto-ausgabe/test
FPM_UID=1000
FPM_GID=1000

Die Beispielpfade müssen ersetzt werden. Eine nicht erreichbare Fotofreigabe wiederherstellen, niemals durch einen leeren Ordner ersetzen. Ein Ausgabeordner kann bewusst separat angelegt werden und muss außerhalb registrierter Quellen liegen. Bind-Mounts erstellen fehlende Hostpfade nicht automatisch.

config/docker/app.toml prüfen. Die neuen Container sehen das Quellarchiv unter /sources/archive, die Ausgabe unter /output. UID/GID 1000 besitzen die neu angelegten Image-Verzeichnisse /data und /cache. Diese IDs müssen die Quellen lesen und das gewählte Ausgabeziel schreiben dürfen. Bei abweichenden IDs zuerst auch die Eigentümer der Anwendungsvolumes passend einrichten; ein geänderter Wert allein ändert keine Dateirechte. Keine rekursive Rechteänderung an Fotos und kein App-/Worker-Betrieb als root.

docker compose config --quiet
docker compose build app
# Bei einem bereits geladenen fertigen Image entfällt der Build.
docker compose run --rm --no-deps app --db /data/inventory.sqlite init
docker compose run --rm --no-deps app --db /data/inventory.sqlite setup-account
docker compose up -d --wait --wait-timeout 120
docker compose ps

Alternativ zur manuellen Ersteinrichtung kann der App-Container mit FPM_INIT=1 eine fehlende Datenbank samt Zugangscode anlegen. Vorhandene Inventare werden weder automatisch migriert noch zurückgesetzt; der Worker wartet auf die gesunde App. Der Code steht beim ersten Start im App-Log.

Den einmaligen Zugangscode privat aufbewahren. Im Browser genau http://localhost:8765 öffnen, Code eingeben und ein Passwort wählen. 127.0.0.1 ist eine andere Origin und wird mit der Standardkonfiguration abgewiesen. Der Port ist nur an Host-Loopback gebunden. Bei einem entfernten NAS kannst du den SSH-Tunnel aus der OMV-Anleitung verwenden oder eine exakte LAN-/Proxy-Origin konfigurieren; Details unter Betrieb und Zugang. Nicht einfach den Port öffentlich freigeben. Es gibt ein lokales Administratorkonto; Familien sind keine voneinander abgeschotteten Benutzerkonten.

Bestehende Installation: Die obigen init-/setup-account-Schritte sind kein Upgrade-Rezept. Zuerst App/Worker stoppen, konsistentes SQLite-Backup erstellen, an einem neuen Pfad wiederherstellen und explizit migrieren. Historische Quellpfade müssen im Container erhalten bleiben oder administrativ neu gebunden werden. Auch ein neuer Compose-Projektname kann andere, leere Volumes auswählen: bisherigen Projektnamen mit docker compose -p NAME beibehalten. Siehe Migration und Update.

Der Workflow in der WebUI

  1. Bibliothek: Familie und konkrete Quelle registrieren, dann „Erfassen“. Bestehende Ordner müssen vorher nicht umsortiert werden. Datenbank/Cache und 90_System dürfen nicht Teil einer registrierten Fotoquelle sein.
  2. Analysieren: Basisanalyse starten, optional Ähnlichkeit/technische Bewertung. Einzelne fehlende RAW-Vorschauen sind kein Nachweis beschädigter Originale.
  3. Prüfen / Bewertungen: Duplikate und Varianten vergleichen, Keeper/Ablehnung ausdrücklich entscheiden, Sterne vergeben und konkrete Dateien auswählen.
  4. Anwenden: Auswahl als Plan speichern, Positionen und Ziele prüfen, Dry-run ausführen und erst dann die Aktion bestätigen. Standardmäßig bleibt Ausführung gesperrt. Für Kopieren zuerst allow_copy = true setzen und beide Dienste neu erstellen. Move/Delete benötigen separate Fähigkeiten und bewusste schreibbare Worker-Mounts; zunächst nur mit synthetischen Testbeständen erproben.
  5. Ergebnis kontrollieren: Auftrag/Dateifortschritt und Zielbestand prüfen, JSONL-Manifest herunterladen. Den geprüften Dateisystemexport anschließend im gewünschten Fotosystem importieren.

Die Übersicht nennt den nächsten Schritt und dessen Begründung. „Aufträge“ zeigt Fortschritt, Probleme und neue Versuche. Browser-/API-Neustart beendet den Worker nicht. Unterbrochene Worker-Aufträge setzen sich nicht automatisch fort.

Was dauerhaft gespeichert wird

Speicher Inhalt und Verantwortung
app-data → /data SQLite inklusive Benutzerzugang, Entscheidungen, Plänen, Job- und Ausführungsjournalen; auf lokalem Datenträger sichern
preview-cache → /cache Regenerierbare Vorschauen, standardmäßig 1 GiB Budget; Worker schreibt, API liest
./config/docker → /config:ro Geprüfte Startkonfiguration; separat sichern
FPM_SOURCE → /sources/archive:ro Bestehende Fotos als Bind-Mount; werden nicht in ein Anwendungsvolume importiert
FPM_OUTPUT → /output Bewusst gewählter Export; nur Worker hat einen schreibbaren Mount
Docker-Logs Rotierendes stdout/stderr, maximal 3 × 10 MiB pro Dienst

Backups der laufenden SQLite-Hauptdatei ohne WAL sind nicht ausreichend. Verwende nach sicherem Stoppen die Backup-Funktion. docker compose down --volumes ist kein Update-Schritt. Nach ausgeführten Moves/Löschungen ist eine alte Datenbank allein kein sicherer Rollback.

Fehler melden

Version, Betriebssystem/Architektur, Dateisystem/Mountart, betroffene Aktion, Reproduktionsschritte und Erwartung angeben. Nur synthetische oder ausdrücklich freigegebene Dateien teilen. Diagnose lokal sammeln:

docker compose run --rm --no-deps app --version
docker compose ps
docker compose logs --no-color --since 30m app worker > family-photo-manager-beta.log

Auftragsbezogene Ereignisse lassen sich in der WebUI unter „Auftrag & technische Details“ herunterladen. Logs, Fehler und Manifeste können private Dateipfade und Namen enthalten. Vor einem Bugreport prüfen/anonymisieren. Keine Datenbank, .env, Passwörter, Zugangscodes, Cookies oder ML-Tokens veröffentlichen. HTTP- Zugriffslogs sind standardmäßig aus; Validierungsfehler spiegeln keine Eingaben.

Lokale Entwicklung und Kompatibilität

uv sync --locked --dev --group analysis --group decoders
uv run family-photo-manager --help
uv run --group analysis --group decoders pytest -q
uv run ruff check .
cd frontend
npm ci
npm run check
npm run build
npx playwright test

Python ≥3.12; geprüft wird 3.12. ExifTool ist für Scans nötig, FFmpeg für Video- Poster. Node wird nur für Entwicklung/Build benötigt. Docker verwendet Node 22.16.0. Weitere Betriebsbefehle, lokale Konfiguration und ML-Grenzen: Operations, Architektur, Projektziel, Repository-Struktur.

Der Anzeigename lautet Family Photo Manager, Distribution/CLI/Image heißen family-photo-manager, das neue Python-Kommando ist python -m family_photo_manager. Der bisherige CLI-Name photo-manager bleibt ein Alias. photo_manager bleibt die bestehende Python-Implementierung, damit Imports, globale Sperren und Klassen nicht verdoppelt werden. ~/.config/photo-manager, Cookie photo_manager, gespeicherte Browserauswahl, Datenbankschema und Modell-/Rezeptkennungen behalten ihre Identität. Compose akzeptiert bisherige PM_*-/PHOTO_*-Variablen als Fallback; neue FPM_* Werte haben Vorrang. Vorhandene Hostordner und Inventarpfade werden nicht umbenannt.

Geplante Plattform- und Performance-Erweiterungen

Native macOS-Unterstützung, AMD64-/ARM64-Docker-Images, ressourcenabhängige Verarbeitung und wählbare schnelle/genaue ML-Profile sind im Plattform- und Performance-Plan beschrieben. Die automatische Ressourcensteuerung und die ML-Profilauswahl sind noch nicht implementiert. Der Plan ergänzt das verbindliche Projektziel.