From 25fbefc703c0531060203bcdb3910a590a6bfdb2 Mon Sep 17 00:00:00 2001 From: Paul Nothaft <53005142+the-luap@users.noreply.github.com> Date: Sat, 22 Aug 2026 21:38:25 +0200 Subject: [PATCH] docs(faces): link the face-recognition guidance from where people look (#1125) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every other feature routes readers to docs.picpeak.app. Face recognition was the one that either pointed somewhere else or pointed at nothing — poor placement for the feature with the highest read-before-you-enable burden anything here ships. .env.example referenced docs/feature-face-recognition.md, which does not exist — and creating it is not the fix, because .gitignore:89 ignores docs/feature-*.md outright, so the file would be invisible to anyone who cloned. That was the only pointer to legal guidance an operator got while editing the variables that turn Art. 9 processing on. Also: the README linked the sidecar's developer README for the feature name and had no row in the documentation table, docs/single-container.md left readers who wanted the feature nowhere to go, ml/README.md had no backlink, and the admin consent callout had no link at all. It does now, inline at the end of the obligation. Reported by @Luca-Timo. --- .env.example | 3 ++- README.md | 3 ++- docs/single-container.md | 4 +++- .../src/components/admin/FaceRecognitionCard.tsx | 16 +++++++++++++++- frontend/src/i18n/locales/de.json | 1 + frontend/src/i18n/locales/en.json | 1 + ml/README.md | 5 +++++ 7 files changed, 29 insertions(+), 4 deletions(-) diff --git a/.env.example b/.env.example index df33b119..544f455a 100644 --- a/.env.example +++ b/.env.example @@ -249,7 +249,8 @@ LOGS=./logs # # Face embeddings are biometric data (GDPR Art. 9 special category in the EU). # The photographer is the controller and needs a lawful basis for the people -# in their photos — see docs/feature-face-recognition.md before enabling. +# in their photos — read https://docs.picpeak.app/features/face-recognition +# before enabling. # # NOT AVAILABLE ON THE ALL-IN-ONE IMAGE. The single-container build sets # PICPEAK_SINGLE_CONTAINER=true and the backend refuses to enable face diff --git a/README.md b/README.md index 9375c70b..89290890 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,7 @@ Unlike expensive SaaS solutions, PicPeak gives you: **For photographers** — drag & drop upload, auto-expiring & password-protected galleries, automated emails, an analytics dashboard, custom themes, a public landing page, and a [Live Slideshow](https://docs.picpeak.app/features/live-slideshow) projector view that auto-picks-up new uploads during live events. -**For clients** — clean mobile-optimized galleries, one-click bulk downloads, smart search, **People in this gallery** face grouping (opt-in per gallery, needs the optional [ML sidecar](ml/README.md)), optional guest uploads, and download protection (watermarking + right-click prevention). +**For clients** — clean mobile-optimized galleries, one-click bulk downloads, smart search, **[People in this gallery](https://docs.picpeak.app/features/face-recognition)** face grouping (opt-in per gallery, needs the optional [ML sidecar](https://github.com/PicPeak/picpeak/blob/main/ml/README.md)), optional guest uploads, and download protection (watermarking + right-click prevention). **Technical** — Docker-ready, automatic thumbnail generation, external media reference mode, smart archiving of expired galleries, S3-compatible [storage backends](https://docs.picpeak.app/features/storage-backends), [webhooks](https://docs.picpeak.app/features/webhooks), and security-first defaults (JWT, rate limiting, CORS). @@ -140,6 +140,7 @@ Full documentation lives at **[docs.picpeak.app](https://docs.picpeak.app)** — | ⚙️ Admin settings reference | [docs.picpeak.app/guides/admin-settings](https://docs.picpeak.app/guides/admin-settings) | | 🎯 Creating events | [docs.picpeak.app/guides/creating-events](https://docs.picpeak.app/guides/creating-events) | | 📽️ Live Slideshow | [docs.picpeak.app/features/live-slideshow](https://docs.picpeak.app/features/live-slideshow) | +| 🙂 People in galleries (face grouping) | [docs.picpeak.app/features/face-recognition](https://docs.picpeak.app/features/face-recognition) | | 💾 Backup & Restore | [docs.picpeak.app/guides/backup-restore](https://docs.picpeak.app/guides/backup-restore) | | 🔌 API reference | [docs.picpeak.app/api](https://docs.picpeak.app/api) | | 🪝 Webhooks | [docs.picpeak.app/features/webhooks](https://docs.picpeak.app/features/webhooks) | diff --git a/docs/single-container.md b/docs/single-container.md index 59a88807..4a957a74 100644 --- a/docs/single-container.md +++ b/docs/single-container.md @@ -234,4 +234,6 @@ docker inspect --format='{{.State.Health.Status}}' picpeak thumbnail and preview generation in one container would slow everything down rather than fail cleanly. The toggle in Settings → Features is disabled here and says so. Use the multi-container deployment if you want - it. + it — see + [People in galleries](https://docs.picpeak.app/features/face-recognition) + for what the feature does and what enabling it commits you to. diff --git a/frontend/src/components/admin/FaceRecognitionCard.tsx b/frontend/src/components/admin/FaceRecognitionCard.tsx index 7d47604d..bc793178 100644 --- a/frontend/src/components/admin/FaceRecognitionCard.tsx +++ b/frontend/src/components/admin/FaceRecognitionCard.tsx @@ -19,7 +19,7 @@ import React, { useEffect, useRef, useState } from 'react'; import { useQuery } from '@tanstack/react-query'; import { useTranslation } from 'react-i18next'; import { toast } from 'react-toastify'; -import { Users, RefreshCw, Trash2, AlertTriangle, ShieldCheck, SlidersHorizontal } from 'lucide-react'; +import { Users, RefreshCw, Trash2, AlertTriangle, ShieldCheck, SlidersHorizontal, ExternalLink } from 'lucide-react'; import { PeopleManagerModal } from './PeopleManagerModal'; import { Button, Card, Loading } from '../common'; @@ -280,6 +280,20 @@ export const FaceRecognitionCard: React.FC = ({ eventI defaultValue: 'Detected faces are personal data, and in the EU they count as a special category. You are the controller for this gallery: make sure you have a lawful basis for the people in these photos before switching this on. Nothing leaves your server — detection runs in your own container.', })} + {/* The guidance is reachable from the one screen where someone is + about to start Art. 9 processing, rather than only from the + README they have not opened (#1125). Inside the consent callout + on purpose: next to the obligation, not filed under help. */} + {' '} + + {t('admin.faces.consentLearnMore', { defaultValue: 'Read the guidance' })} + +

diff --git a/frontend/src/i18n/locales/de.json b/frontend/src/i18n/locales/de.json index b6114925..0c655351 100644 --- a/frontend/src/i18n/locales/de.json +++ b/frontend/src/i18n/locales/de.json @@ -3158,6 +3158,7 @@ "title": "Personen in dieser Galerie", "subtitle": "Fotos nach den abgebildeten Personen gruppieren, damit Gäste ihre eigenen finden und herunterladen können.", "consentNotice": "Erkannte Gesichter sind personenbezogene Daten und gelten in der EU als besondere Kategorie. Sie sind für diese Galerie verantwortlich: Stellen Sie sicher, dass Sie eine Rechtsgrundlage für die abgebildeten Personen haben, bevor Sie dies aktivieren. Nichts verlässt Ihren Server — die Erkennung läuft in Ihrem eigenen Container.", + "consentLearnMore": "Hinweise lesen", "enable": "Personen in dieser Galerie erkennen", "enableHint": "Vorhandene Fotos werden im Hintergrund durchsucht. Gesichter und ihre numerischen Signaturen werden in Ihrer Datenbank gespeichert; sie sind niemals in Backups oder Exporten enthalten.", "visible": "Personenleiste für Gäste anzeigen", diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json index 940cbd1c..8e35f594 100644 --- a/frontend/src/i18n/locales/en.json +++ b/frontend/src/i18n/locales/en.json @@ -2730,6 +2730,7 @@ "title": "People in this gallery", "subtitle": "Group photos by the people in them, so guests can find and download their own.", "consentNotice": "Detected faces are personal data, and in the EU they count as a special category. You are the controller for this gallery: make sure you have a lawful basis for the people in these photos before switching this on. Nothing leaves your server — detection runs in your own container.", + "consentLearnMore": "Read the guidance", "enable": "Detect people in this gallery", "enableHint": "Existing photos are scanned in the background. Faces and their numeric signatures are stored in your database; they are never included in backups or exports.", "visible": "Show the people bar to guests", diff --git a/ml/README.md b/ml/README.md index ea9197cf..fffd1871 100644 --- a/ml/README.md +++ b/ml/README.md @@ -1,5 +1,10 @@ # picpeak-ml +> **Looking for how to use the feature?** → +> [docs.picpeak.app/features/face-recognition](https://docs.picpeak.app/features/face-recognition) +> covers enabling it, the per-gallery toggle, consent and what guests see. +> This document is the sidecar's HTTP contract and deployment notes. + Optional face-detection sidecar for PicPeak (#1074). Detects faces in one image and returns a bounding box, five landmarks, quality signals and a 512-d embedding per face.