From 60e16e967c2632a13886576ef2c935a7bce34b40 Mon Sep 17 00:00:00 2001 From: Holden Salomon Date: Fri, 12 Jun 2026 16:55:35 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20update=20for=200.2.10=20=E2=80=94=20cpu?= =?UTF-8?q?=20tag,=20scheduling=20modes,=20VERBOSE,=20GPU=20troubleshootin?= =?UTF-8?q?g,=20401=20error?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- FAQ.md | 2 +- Setup.md | 39 ++++++++++++++++++++++++++++++++------- Troubleshooting.md | 25 +++++++++++++++++++++++-- 3 files changed, 56 insertions(+), 10 deletions(-) diff --git a/FAQ.md b/FAQ.md index 03dc205..666db6b 100644 --- a/FAQ.md +++ b/FAQ.md @@ -60,4 +60,4 @@ docker compose pull docker compose up -d ``` -The `latest` tag on GHCR tracks the `main` branch. Pinning to a version tag (e.g. `ghcr.io/sudolulo/winnow:v0.2.0`) is recommended for stability. +The `latest` and `cpu` tags on GHCR track the `main` branch. Pinning to a specific version is recommended for stability, but winnow doesn't publish versioned image tags — `latest` / `cpu` are the stable release tags, and `dev` / `dev-cpu` are pre-release. diff --git a/Setup.md b/Setup.md index c0dc64c..d0a4157 100644 --- a/Setup.md +++ b/Setup.md @@ -21,7 +21,16 @@ This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`. --- -## 3. Deploy with Docker Compose +## 3. Choose an image tag + +| Tag | Arch | GPU | Notes | +| :-- | :-- | :-- | :-- | +| `:latest` | amd64 + arm64 | CUDA 13.3 (amd64) | Requires NVIDIA Container Toolkit on amd64 | +| `:cpu` | amd64 | None | ~2 GB smaller; use if you have no NVIDIA GPU | + +Use `:cpu` if your host has no NVIDIA GPU — it skips the entire CUDA stack and runs InsightFace on CPU. + +## 4. Deploy with Docker Compose Copy [`compose.yml`](../compose.yml) and [`.env.example`](../.env.example) to a directory on your host: @@ -65,7 +74,7 @@ docker compose logs -f winnow --- -## 4. First run +## 5. First run On the first run, winnow downloads the embedding models (~1–2 GB) from HuggingFace and InsightFace. This happens once — subsequent runs use the cached models from your mounted volume and start immediately. @@ -73,13 +82,21 @@ On the first run, winnow downloads the embedding models (~1–2 GB) from Hugging ## 5. Scheduling -Set `CRON_SCHEDULE` in your `.env` to keep winnow running on a schedule: +`CRON_SCHEDULE` controls both the run schedule and container lifetime: + +| `CRON_SCHEDULE` | Behaviour | +| :-- | :-- | +| *(unset)* | Run once on startup, then exit | +| *(empty string)* | Stay alive; trigger manually with `docker exec -it winnow winnow` | +| Cron expression | Run on startup, then repeat on schedule | + +Example — every Sunday at 3 AM: ``` -CRON_SCHEDULE=0 3 * * 0 # Every Sunday at 3 AM +CRON_SCHEDULE=0 3 * * 0 ``` -Without `CRON_SCHEDULE`, the container runs once and exits. +In scheduled mode the process (and loaded models) stays resident between runs, so each subsequent run starts immediately without re-loading models. --- @@ -89,7 +106,15 @@ To enable GPU acceleration, include the `deploy` block in `compose.yml` (already ```bash # Verify GPU is accessible to Docker -docker run --rm --gpus all nvidia/cuda:12.9.2-base-ubuntu22.04 nvidia-smi +docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi ``` -CPU mode works without any GPU setup — set `FORCE_CPU=true` to disable GPU explicitly. +CPU mode works without any GPU setup — set `FORCE_CPU=true` to disable GPU explicitly, or use the `:cpu` image tag which omits the CUDA base entirely (~2 GB smaller). + +## Debugging + +Set `VERBOSE=true` in your `.env` to enable DEBUG-level output on the console. The log file (`/app/winnow.log`) always captures DEBUG regardless of this setting — useful when diagnosing issues without a shell into the container: + +```bash +docker exec winnow cat /app/winnow.log +``` diff --git a/Troubleshooting.md b/Troubleshooting.md index 4e391f4..4d8b3df 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -13,6 +13,24 @@ Common causes: --- +## "Immich API key is invalid or expired (401 Unauthorized)" + +Your API key has been revoked or expired. Generate a new one in Immich → **Account Settings** → **API Keys** and update `API_KEY` in your `.env`. + +--- + +## Getting more log detail + +Set `VERBOSE=true` in `.env` (or pass `-e VERBOSE=true`) to enable DEBUG-level output on the console. Useful for tracing exactly which images are being fetched, filtered, and selected. + +The log file at `/app/winnow.log` always captures DEBUG regardless of `VERBOSE`: + +```bash +docker exec winnow cat /app/winnow.log +``` + +--- + ## "No people found" / nothing processed - Make sure Immich has completed face recognition and you have named people in your library @@ -41,11 +59,14 @@ winnow downloads InsightFace and HuggingFace (SigLIP) models on first run. ## Running on CPU (no GPU) -Set `FORCE_CPU=true`. Everything works but embedding computation is slower — expect several minutes per person instead of seconds. +Use the `:cpu` image tag (`ghcr.io/sudolulo/winnow:cpu`) which omits the CUDA base entirely. Or set `FORCE_CPU=true` with `:latest` to disable GPU at runtime. + +Everything works on CPU but embedding computation is slower — expect several minutes per person instead of seconds. If you have a GPU but it's not being used: -- Confirm the NVIDIA container toolkit is installed: `docker run --rm --gpus all nvidia/cuda:12.9.2-base-ubuntu22.04 nvidia-smi` +- Confirm the NVIDIA container toolkit is installed: `docker run --rm --gpus all nvidia/cuda:13.3.0-base-ubuntu22.04 nvidia-smi` - Confirm the `deploy.resources.reservations.devices` block is present in `compose.yml` +- Set `VERBOSE=true` and check the logs — winnow logs which ONNX execution providers are active at startup (should show `CUDAExecutionProvider`) ---