bppicker 0.2.2__tar.gz → 0.2.3__tar.gz

{bppicker-0.2.2 → bppicker-0.2.3}/.eslint-globals.json

@@ -25,6 +25,8 @@
   "MODELS_CHANGED_EVENT": "writable",
   "MONTHS_FULL": "writable",
   "MONTHS_SHORT": "writable",
+  "NO_PICKER_LIBRARY_MESSAGE": "writable",
+  "NO_PICKER_MESSAGE": "writable",
   "NUDGE_DEFS": "writable",
   "RESUME_TEXT": "writable",
   "ROW_LIFECYCLE": "writable",
@@ -769,6 +771,7 @@
   "petsFilter": "writable",
   "petsSort": "writable",
   "photos": "writable",
+  "pickFolder": "writable",
   "pickTagSuggestion": "writable",
   "pickable": "writable",
   "planBootHealth": "writable",

{bppicker-0.2.2 → bppicker-0.2.3}/CHANGELOG.md

@@ -6,6 +6,40 @@ this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.3] — 2026-11-03
+
+### Added
+- **A ready-made Docker image for Linux servers**,
+  `ghcr.io/arkalogy/bppicker`, for Intel and 64-bit ARM (not yet
+  tried on a NAS). Run it headless
+  (`bpp run` copies the best photos of a folder into another one) or run
+  the full app, published to the server's loopback and opened with the
+  keyed link in `docker logs`. The README's Docker section has the
+  commands. The image keeps the boot key on, so other containers and
+  users on the server get a locked page.
+
+### Fixed
+- **Face grouping no longer hangs on Linux.** Worker processes were
+  started by copying the running server, background threads and all,
+  and the face-extraction worker could wait forever, ending after ten
+  minutes with no faces. Workers now start fresh on every system, as
+  they already did on macOS.
+- **Intel processors without AVX** (many NAS Celerons and Atoms) no
+  longer crash analysis. MediaPipe's library needs AVX; the app now
+  checks once at start-up, skips the MediaPipe scorers (pose,
+  expression, hand, subject segmentation, BlazeFace short-range) with
+  one warning, and doesn't download their models.
+- **No install buttons where installs can't work.** When pip can't
+  write anywhere (the Docker image), the app no longer offers in-app
+  installs that would fail.
+- **Browse buttons say when there is no folder picker.** Off macOS the
+  button failed with an error; it now asks you to type the path.
+- **`bpp model accept-attribution` without a terminal** explains how to
+  confirm instead of ending in a traceback.
+- **Export and open-folder no longer trust a home folder of `/`**, which
+  a service account or a container user can have; it would have
+  allowed every path.
+
 ## [0.2.2] — 2026-10-24
 
 ### Fixed
@@ -584,7 +618,8 @@ External calls are limited to documented features:
   desktop wrapper currently builds only the macOS bundle.
 - Python 3.11 only (CI tests this version; 3.12+ is unvalidated).
 
-[Unreleased]: https://github.com/Arkalogy/best-photo-picker/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/Arkalogy/best-photo-picker/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.3
 [0.2.2]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.2
 [0.2.1]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.1
 [0.2.0]: https://github.com/Arkalogy/best-photo-picker/releases/tag/v0.2.0

bppicker-0.2.3/Dockerfile

@@ -0,0 +1,130 @@
+# Self-hosting image, published to the GitHub Container Registry:
+#     docker pull ghcr.io/arkalogy/bppicker
+# Two ways to use it (README "Docker" section has the full commands):
+#   * headless: `bpp run` picks the best photos from a mounted folder and
+#     copies them to another mounted folder; no browser needed;
+#   * the full app: `bpp serve` (the default command), published to the
+#     host's loopback only, opened with the keyed link it prints, and
+#     reached from another computer through an SSH tunnel.
+# Build it yourself with `docker build -t bppicker .`.
+#
+# The image installs only pip wheels (no compiler): the web, HEIC and
+# camera-RAW extras plus the wheel-only part of the `faces` extra
+# (mediapipe, ai-edge-litert, scipy), which the pose, expression,
+# segmentation and BlazeFace scorers need. A test keeps that list equal
+# to `faces` in pyproject.toml. Only dlib / face_recognition are left out:
+# they need a compiler, and their bundled landmark model has
+# non-commercial training-data terms, so this image does not
+# redistribute it. The default face models (YuNet / SFace) download at
+# first use after the license prompt, exactly as in the app; the only
+# model files in the image are the two small ones that ship inside the
+# packages (bpp's BlazeFace short-range and OpenCV's Haar cascade).
+FROM python:3.11-slim
+
+# libgl1 / libglib2.0-0: mediapipe pulls in the full (non-headless)
+# opencv-contrib-python wheel, which loads them at import time.
+# libegl1 / libgles2: mediapipe's native Tasks library links EGL and
+# GLES; without them every mediapipe scorer fails to load.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 libglib2.0-0 libegl1 libgles2 && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+# Dependencies first, in a layer that depends only on pyproject.toml, so
+# a code change doesn't reinstall them: install against an empty
+# package, then drop it.
+# (README.md is a stub here, so a docs edit doesn't bust this layer.)
+COPY pyproject.toml ./
+RUN mkdir bpp && touch bpp/__init__.py README.md \
+    && pip install --no-cache-dir ".[web,heic,raw]" \
+        "scipy>=1.10" "mediapipe>=0.10" "ai-edge-litert>=2.1" \
+    && pip uninstall -y bppicker && rm -rf bpp README.md
+COPY README.md ./
+COPY bpp/ bpp/
+RUN pip install --no-cache-dir --no-deps . && rm -rf /app/bpp
+
+# Fail the build, not the user, if a native library is missing: import
+# every optional scorer package, then load mediapipe's Tasks library the
+# way the app does (cpu_support._PROBE). mediapipe goes last: exit 132
+# (SIGILL) means the builder has no AVX (an emulated amd64 build), which
+# the app checks for at run time, so only warn, with everything else
+# already checked.
+RUN python -c "import cv2, scipy, ai_edge_litert.interpreter, pillow_heif, rawpy, onnxruntime, flask, bpp" \
+    && python -c "from bpp.scoring.cpu_support import _PROBE; exec(_PROBE)"; \
+    rc=$?; if [ "$rc" -eq 132 ]; then echo "warning: no AVX here; mediapipe load not checked"; \
+    elif [ "$rc" -ne 0 ]; then exit "$rc"; fi
+
+# License notices travel with the image. NOTICE.txt lists the GPL / LGPL
+# native libraries the wheels bundle and the written offer for their
+# source.
+COPY LICENSE NOTICE.txt /usr/share/doc/bppicker/
+
+# Non-root user — defence-in-depth if an RCE is found
+RUN useradd --create-home --shell /bin/false bpp \
+    && mkdir -p /data && chown bpp /data
+USER bpp
+
+# Keep downloaded models and model acceptances on the volume so they
+# survive container re-creation (default would be the container's home).
+# HOME too: run with `--user "$(id -u):$(id -g)"` the uid has no passwd
+# entry, and HOME would fall back to `/`, which the export and
+# open-folder path checks would then treat as the home folder.
+# PYTHONNOUSERSITE: the image's packages are fixed; without it an in-app
+# install would land in /data/.local and shadow them across upgrades.
+ENV HOME=/data \
+    BPP_CACHE_DIR=/data/.cache/bpp \
+    XDG_CONFIG_HOME=/data/.config \
+    PYTHONNOUSERSITE=1
+
+EXPOSE 5001
+
+# Liveness probe. It must hit a path the auth gate lets through WITHOUT a
+# token: every /api/* route (including /api/v1/health) requires the
+# per-boot app session token, which only the rendered index page carries,
+# so probing /api/v1/health would get a 403 and mark the container
+# unhealthy forever. /static/* is public by design (see
+# bpp/web/share.py:authorize_request), a static file contains no secrets,
+# and the request still runs the full Flask middleware (auth gate + DB
+# connection), so a wedged server fails the probe. The probe originates
+# inside the container (127.0.0.1 = loopback), so the LAN gate never
+# blocks it. Pinned by tests/test_docker_healthcheck.py.
+# start-period covers the processor check at start-up (cpu_support: up to
+# 120 s on a slow NAS) before the server listens.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=150s --retries=3 \
+    CMD python3 -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/static/manifest.json', timeout=4)" || exit 1
+
+VOLUME /data
+
+# Trust the Docker bridge gateway range AND Docker Desktop's host
+# alias range. Requests whose immediate peer IP is in these ranges are
+# treated exactly like loopback: like a local browser, they still need
+# the boot key (below) before the page hands over the owner token. That
+# is what lets you use your own container from the host browser, because
+# host traffic reaches the container from the bridge gateway, not from
+# 127.0.0.1. The ranges also cover every other container on the same
+# Docker network, which is why the boot key stays on. (X-Forwarded-For is NOT consulted here; that additionally
+# needs `behind_proxy: true` in the config — see bpp/commands/serve.py.)
+#
+# CRITICAL: this is only safe if the container port is published to
+# host loopback:
+#     docker run -p 127.0.0.1:5001:5001 -v /path/to/library:/data <image>
+# If you publish to all interfaces (`-p 5001:5001`), other machines on
+# your network can reach the port, and their traffic can also arrive
+# from an address inside these trusted ranges (e.g. via Docker
+# Desktop's port forwarder): only the boot key would stand between
+# them and owner access. LAN Sharing (phone access with device pairing) is therefore
+# not a supported container setup: with a loopback-only publish phones
+# can't reach the port, and with an all-interfaces publish whether LAN
+# clients look like the trusted gateway depends on the Docker platform.
+# For phone access, run bpp natively and use LAN Sharing there.
+ENV BPP_TRUSTED_PROXIES=172.16.0.0/12,192.168.65.0/24
+
+# Bind 0.0.0.0 INSIDE the container so Docker's port mapping can reach
+# the server (a loopback bind inside the container is unreachable from
+# the host). Exposure to the outside world is decided by the `-p` flag
+# above, not by this bind.
+# No --open-loopback: the server prints a keyed link
+# (http://127.0.0.1:5001/?_boot=...) to `docker logs`, or takes a fixed
+# key from BPP_BOOT_SECRET. Other containers and local users who can
+# reach the port get a locked page without it.
+CMD ["bpp", "serve", "--library", "/data", "--host", "0.0.0.0", "--no-browser"]

{bppicker-0.2.2 → bppicker-0.2.3}/NOTICE.txt

@@ -23,6 +23,9 @@ Trust model summary
 - **Desktop app (.app / DMG)**: built with the optional extras
   installed, so it DOES contain those LGPL / GPL components.
   See "Desktop app (.app / DMG)" below.
+- **Docker image**: built with the HEIC and RAW extras and most of
+  `faces`, so it contains the same kind of LGPL / GPL components.
+  See "Docker image" below.
 - **Downloaded at first-use**: ML model weights fetched on demand,
   some from the original publisher and some from third-party
   re-hosts (listed per model below), never from Arkalogy. Some
@@ -285,6 +288,37 @@ source code for any GPL- or LGPL-licensed component listed in that
 release's inventory, for no more than the cost of providing it. Email
 support@arkalogy.com with the release version and the component name.
 
+================================================================
+Docker image (ghcr.io/arkalogy/bppicker)
+================================================================
+
+The self-hosting image is built from `python:3.11-slim` (Debian) with
+`pip install ".[web,heic,raw]"` plus mediapipe, ai-edge-litert and
+SciPy from the `faces` extra (not face_recognition or dlib). Like the
+desktop app, it therefore contains the optional runtime components
+and the native libraries their Linux wheels bundle, among others:
+
+- pillow-heif with libx265 (GPL-2.0), libheif and libde265 (LGPL-3.0)
+- rawpy with LibRaw (LGPL-2.1)
+- FFmpeg libraries from the OpenCV wheels (LGPL-2.1), including
+  opencv-contrib-python, which mediapipe requires; that wheel also
+  bundles Qt 5 (LGPL-3.0) with the X11 / xcb libraries it uses, and
+  its full list and license texts ship in the image as
+  `opencv_contrib_python-*.dist-info/LICENSE-3RD-PARTY.txt`
+- the Debian packages of the base image and the ones the image adds
+  (libgl1, libglib2.0-0, libegl1, libgles2), each under its own
+  license, listed in the image under /usr/share/doc/
+
+This file and LICENSE are in the image at /usr/share/doc/bppicker/.
+No model weights other than the two bundled detectors above are in
+the image; the rest download at first use.
+
+Written offer. For at least three years after each image is
+published, Arkalogy will provide, to anyone who asks, the complete
+corresponding source code for any GPL- or LGPL-licensed component in
+that image, for no more than the cost of providing it. Email
+support@arkalogy.com with the image tag and the component name.
+
 Build toolchain
 ---------------
 

{bppicker-0.2.2 → bppicker-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bppicker
-Version: 0.2.2
+Version: 0.2.3
 Summary: Local-first photo curation tool — score, deduplicate, and select the best photos from large collections
 Project-URL: Homepage, https://github.com/Arkalogy/best-photo-picker
 Project-URL: Repository, https://github.com/Arkalogy/best-photo-picker
@@ -70,20 +70,22 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Arkalogy/best-photo-picker/blob/main/LICENSE)
 [![Python 3.11](https://img.shields.io/badge/python-3.11-green.svg)](https://www.python.org/downloads/)
 
-**Drowning in 15,000 family photos?** Apple Photos and Google Photos bury your best shots in their feed. Best Photo Picker runs entirely on your machine, scores every photo on sharpness, lighting, faces, and composition, and lets you curate the perfect 50 in minutes once it's analyzed — no cloud, no subscription, no compromise.
+Best Photo Picker scores a photo library on your own computer (sharpness, exposure, faces, composition), groups faces into people, folds near-duplicates, and gives you the best photos of the people you choose. Free, MIT, no account.
 
 It **auto-scores your whole library for curation without uploading anything**, **clusters the near-duplicates**, and lets you **boost specific people** so the final pick favors the faces that matter — your kid, for the grandparents.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Arkalogy/best-photo-picker/main/docs/screenshots/demo.gif" width="720" alt="Demo: a library of thousands of photos, open one child's photos, BPP Picks narrows them to her best shots, then the top pick opens with its sharpness, exposure, faces and composition scores">
-  <br><sub>The recording and the screenshots show a sample library built from stock photos of models (<a href="https://www.pexels.com/license/">Pexels</a>) plus generated test images, not the author's family.</sub>
+  <img src="https://raw.githubusercontent.com/Arkalogy/best-photo-picker/main/docs/screenshots/demo.gif" width="800" alt="Demo: a library of 3,848 photos; Mia is picked from Faces and BPP Picks narrows her 26 photos to her best 7; the Family group gives its best 5; the winning photo opens with its sharpness, exposure, faces and composition scores">
+  <br><sub>The recording and the screenshots show a sample library of stock photos (<a href="https://www.pexels.com/license/">Pexels</a>) and generated test images.</sub>
 </p>
 
 > **Try it — no photos needed** (needs Python 3.11: `brew install python@3.11` on a Mac, or use the [desktop app](#desktop-app-macos-apple-silicon)):
 > ```bash
-> pipx install --python python3.11 "bppicker[web]" && bpp demo
+> pipx install --python 3.11 "bppicker[web]" && bpp demo
 > ```
-> Generates a sample library, runs the full UI locally, and deletes the sample library when you stop it (Ctrl+C). **The first analysis asks before downloading the on-device AI models (up to ~660 MB, mostly CLIP for visual search); they're cached, so that's a one-time download.** Your photos are never uploaded. bpp still makes a few small network calls of its own (a signed model-registry check at startup, an update check, map tiles) — all listed under [Privacy](#privacy).
+> Generates a sample library, runs the full UI locally, and deletes the sample library when you stop it (Ctrl+C). **The first analysis asks before downloading the on-device AI models (about 660 MB for the default set, mostly CLIP for visual search; optional features fetch their own later); they're cached, so that's a one-time download.** Your photos are never uploaded. bpp still makes a few small network calls of its own (a signed model-registry check at startup, an update check, map tiles) — all listed under [Privacy](#privacy).
+
+**[Website and Mac download →](https://arkalogy.github.io/best-photo-picker/)**
 
 *By Arkadiy Birger at [Arkalogy](https://arkalogy.com) — a PM-directed, AI-built product; the architectural decisions are captured in [`docs/adr/`](https://github.com/Arkalogy/best-photo-picker/tree/main/docs/adr). [Why & how it was built →](#about)*
 
@@ -96,11 +98,13 @@ More screenshots (faces, calendar, map, duplicates, the editor) and an annotated
 Where it fits next to what you already use:
 
 - **Apple Photos / Google Photos** are great at storing and browsing. bpp ranks and curates — and runs alongside them.
-- **Lightroom, Aftershoot, Excire** are built for photographers culling a shoot. bpp is built for a family library that spans years — and it's free and open source.
+- **Lightroom, Aftershoot, Narrative Select, Excire** are built for photographers culling a shoot. bpp is built for a family library that spans years — and it's free and open source.
 - **digiKam / Immich** organize and manage your collection. bpp answers one question: which fifty are the best of *this person*?
 
 If you live in the Apple/Google ecosystem and your collection fits their feeds, those tools work great. **bpp exists for the case they're bad at: you have thousands of photos of a specific subject — your kid, your dog, last summer's trip — and you want to find the actual best fifty without uploading anything anywhere.**
 
+<sub>Other product names are trademarks of their respective owners; bpp is not affiliated with or endorsed by them.</sub>
+
 ## How it's built
 
 Claude writes the code. I own the product and the architecture, and nothing ships without my sign-off. What keeps that honest:
@@ -114,7 +118,7 @@ Claude writes the code. I own the product and the architecture, and nothing ship
 
 - The pip install needs Python 3.11 exactly
 - The Mac app is Apple Silicon only; Windows should work via pip but hasn't been tested end to end
-- The first analysis downloads up to about 660 MB of models (it asks first); after that they're cached
+- The first analysis downloads about 660 MB of models (it asks first; optional features fetch their own later); after that they're cached
 - Face detection occasionally finds a face in a dog, a plate of food, or a flower bed. One click on **Not a face** fixes it.
 
 ## Features
@@ -124,7 +128,8 @@ Claude writes the code. I own the product and the architecture, and nothing ship
 - **Temporal diversity** — per-day caps and monthly coverage for balanced selection
 - **Face recognition** — automatic clustering, per-person smart albums, merge, dismiss, reassign, drag-to-fix mis-detected bboxes
 - **Library management** — import by copying to managed library with SHA-256 dedup
-- **Album system** — manual + 20 smart album types (person, time, score, duplicates, pets, etc.)
+- **Album system** — manual + 19 smart album types (person, time, score, duplicates, pets, etc.)
+- **Sensitive-photo check (opt-in)** — an optional NudeNet model, downloaded only after you accept its license, flags photos that may be sensitive (bath time, the beach) into a Sensitive album; set Settings → Scoring → Sensitive photos to Exclude to keep them out of auto-picks you plan to share
 - **Interactive web UI** — real-time slider tuning, photo grid, lightbox, compare view, batch operations
 - **Desktop app** — native macOS app via Tauri v2 (wraps the web UI in a native window)
 - **Soft delete** — 30-day recovery, Recently Deleted album
@@ -145,13 +150,13 @@ Recommended — [pipx](https://pipx.pypa.io/) keeps bpp in its own
 environment and makes updating one command:
 
 ```bash
-pipx install --python python3.11 "bppicker[web]"
+pipx install --python 3.11 "bppicker[web,heic,raw]"
 
 # Update to the latest release later:
 pipx upgrade bppicker
 ```
 
-`--python python3.11` matters: pipx otherwise uses whatever Python it
+`--python 3.11` matters: pipx otherwise uses whatever Python it
 was installed with (Homebrew's is newer), and the install ends with
 "No matching distribution found for bppicker".
 
@@ -191,7 +196,7 @@ update, download the newer `.dmg` the same way; your photo library and
 settings live outside the app and carry over untouched.
 
 > Apple Silicon (M1/M2/M3 and later) only. On an Intel Mac, or on
-> Windows/Linux, use the `pipx install --python python3.11 "bppicker[web]"` path above.
+> Windows/Linux, use the `pipx install --python 3.11 "bppicker[web,heic,raw]"` path above.
 
 ### Try the Demo
 
@@ -204,7 +209,8 @@ Generates sample photos and launches the web UI — no configuration needed.
 ### Library Mode (Recommended)
 
 ```bash
-# Start the photo management server (default library: ~/Pictures/BestPhotoPicker)
+# Start the photo management server (default: the library you used last, or
+# BestPhotoPicker inside the Pictures folder of your home directory, on every OS)
 bpp serve
 
 # Or specify a custom library path
@@ -297,7 +303,7 @@ crashing. Ordering matters — providers are tried in the order listed.
 |---|---|---|---|
 | **macOS arm64** (M1/M2/M3) — CPU | no (tested locally on the dev Mac) | yes | Primary dev target. Tauri desktop app ships only this. |
 | **Linux x86_64** — CPU | yes (`ubuntu-latest`) | yes | Default for PyPI install. |
-| **Linux arm64** — CPU | no | yes | A Dockerfile ships, but the image has never been built in CI; runtime not exercised in CI. |
+| **Linux arm64** — CPU | image build at each release | yes | The Docker image is built for arm64 when a release is published; the arm64 test suite runs on demand only. |
 | **Windows** — CPU | no | yes | Code path exists; never run end-to-end. Reports welcome via GitHub issues. |
 | **macOS arm64** — CoreMLExecutionProvider (ANE) | no | yes | Code path exists. Expected 5-10× face inference speedup; correctness depends on the specific ONNX graph and ONNX Runtime version. |
 | **Linux x86_64** — CUDAExecutionProvider | no | yes | Requires `pip install onnxruntime-gpu` (replaces base `onnxruntime`). Free-tier CI doesn't have a GPU runner. |
@@ -426,22 +432,90 @@ A double-clickable launcher template ships at
 window with the documented default library path. Override via
 `BPP_LIBRARY` env var.
 
-A `Dockerfile` ships at the repo root for self-hosters who want to
-build their own image (`docker build -t bppicker .`). No prebuilt
-image is published and the Dockerfile is not built in CI, so treat
-it as untested. It's a multi-stage build that installs the
-`[web,faces,heic]` extras, and it keeps downloaded models and
-model-license acceptances on the `/data` volume
-(`BPP_CACHE_DIR=/data/.cache/bpp`, `XDG_CONFIG_HOME=/data/.config`)
-so they survive re-creating the container. The server binds
-`0.0.0.0` inside the container (needed for port mapping); publish
-only to host loopback:
-`docker run -p 127.0.0.1:5001:5001 -v /path/to/library:/data bppicker`.
-The image sets `BPP_TRUSTED_PROXIES` to the Docker bridge ranges, so
-requests through that mapping are treated as the owner — publishing
-to all interfaces (`-p 5001:5001`) can give other machines on your
-network owner access. LAN sharing is not supported from a container.
-Behind a reverse proxy, `X-Forwarded-For` is honored only if you also
+### Docker
+
+A self-hosting image is published to the GitHub Container Registry
+for `linux/amd64` and `linux/arm64`:
+
+```bash
+docker pull ghcr.io/arkalogy/bppicker
+```
+
+It has the web, HEIC and camera RAW support and every scorer except
+the legacy dlib face backend. Apart from two small detectors that ship
+inside the packages, models download on first use into the `/data`
+volume, along with your model-license acceptances, so both survive
+re-creating the container. Create the host folders you mount before
+the first run: `--user` runs the container as you, so the files it
+writes are yours, and Docker would otherwise create missing folders
+owned by root, which the container then can't write to. There are two
+ways to use it.
+
+Built and run on Linux x86-64 and arm64 machines; it has not yet been
+tried on a Synology, QNAP or Unraid box, so reports from one are welcome
+in GitHub issues.
+
+**Headless, on a NAS or server.** Point it at a photo folder and the
+best photos are copied into another folder; your originals are
+mounted read-only. Accept the free-license face models once (this
+shows the terms and asks you to confirm), then run picks as often as
+you like:
+
+```bash
+docker run --rm -it --no-healthcheck --user "$(id -u):$(id -g)" \
+    -v /path/to/bpp-data:/data ghcr.io/arkalogy/bppicker \
+    bpp model accept-attribution
+docker run --rm --no-healthcheck --user "$(id -u):$(id -g)" \
+    -v /path/to/bpp-data:/data \
+    -v /path/to/photos:/photos:ro -v /path/to/best:/best \
+    ghcr.io/arkalogy/bppicker \
+    bpp run --input /photos --k 50 --out /best --copy
+```
+
+Use `--copy` rather than `--symlink` here: a link made inside the
+container points at `/photos/...`, which doesn't exist on the host.
+`--no-healthcheck` because the image's health check watches the
+app's web server, which a headless run doesn't start.
+
+**The full app.** `bpp serve` is the image's default command. Publish
+the port to the host's loopback only, and mount your photos so you
+can import them from `/photos`:
+
+```bash
+docker run -d --name bpp --user "$(id -u):$(id -g)" -p 127.0.0.1:5001:5001 \
+    -v /path/to/library:/data -v /path/to/photos:/photos:ro \
+    ghcr.io/arkalogy/bppicker
+docker logs bpp 2>&1 | grep 'Open Best Photo Picker at' | tail -1
+```
+
+The second command shows the link to open, which carries a key the
+server makes at each start (`http://127.0.0.1:5001/?_boot=...`); after
+a restart, run it again for the new one. If you publish a different
+host port (`-p 127.0.0.1:8080:5001`), change the port in the link to
+match.
+Without the key the app shows a locked page, so other containers and
+other users on the server can't get in. On the same machine, open the
+link. From another computer, start an SSH tunnel first (`ssh -L
+5001:127.0.0.1:5001 you@your-server`), then open the same link there.
+A reload keeps working; a new tab or browser session needs the link
+again. In the app, type `/photos` into the import box (the folder
+picker only works on a Mac), and export into a folder under `/data`,
+which is your library folder on the host. Reaching the app directly
+from another computer on your network, with a login, is planned for a
+later release.
+
+Why loopback only: the image sets `BPP_TRUSTED_PROXIES` to the Docker
+bridge ranges, so requests through that mapping count as local, and
+only the key stands between them and owner access. Publishing to all
+interfaces (`-p 5001:5001`) lets other machines on your network reach
+that locked page too. Don't put the container behind a reverse proxy
+for the same reason. LAN sharing (phone pairing) is not supported from
+a container, and neither is installing extra features from inside the
+app (such as object removal): the image's packages are fixed.
+
+To build the image yourself: `docker build -t bppicker .`
+
+Running natively behind a reverse proxy, `X-Forwarded-For` is honored only if you also
 set `behind_proxy: true` in the config, and the proxy's host name must
 be listed in `BPP_TRUSTED_HOSTS` (the server answers only to its own
 addresses); see