docs: add wiki, .env.example, and fix stale if-curator references

- Add docs/setup.md, docs/troubleshooting.md, docs/faq.md as user-facing wiki
- Add .env.example with all env vars and inline comments
- Fix compose.override.yml: rename service if-curator → winnow, update volume paths
- Fix CHANGELOG.md: rename if-curator → winnow in release notes
- Link docs from README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-06-12 01:26:24 +00:00
co-authored by Claude Sonnet 4.6
parent eea7baa19f
commit b7dc87b05b
7 changed files with 280 additions and 5 deletions
+77
View File
@@ -0,0 +1,77 @@
# Troubleshooting
## Container exits immediately
Check logs:
```bash
docker compose logs winnow
```
Common causes:
- **Missing required env var** — `IMMICH_URL` or `API_KEY` not set
- **Cannot reach Immich** — check the URL and that Immich is running; use `http://` not `https://` unless you have TLS set up
---
## "No people found" / nothing processed
- Make sure Immich has completed face recognition and you have named people in your library
- `YEARS_FILTER` defaults to 10 years — increase it if your tagged photos are older
- `MIN_FACE_COUNT` skips people with few photos — lower or remove it
---
## Frigate upload fails
- Confirm `FRIGATE_URL` is reachable from inside the container: `docker exec winnow curl $FRIGATE_URL/api/stats`
- Check Frigate v0.16+ — older versions don't have the face training API
- Set `DRY_RUN=true` to verify selection without uploading
---
## Models fail to download
winnow downloads InsightFace and HuggingFace (SigLIP) models on first run.
- Ensure the container has internet access
- Confirm the model volume is mounted and writable
- If behind a proxy, set `HTTP_PROXY` / `HTTPS_PROXY` env vars
---
## Running on CPU (no GPU)
Set `FORCE_CPU=true`. Everything works 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 `deploy.resources.reservations.devices` block is present in `compose.yml`
---
## Same images uploaded every run
The upload tracker is stored in `CACHE_DIR` (`/app/.if_cache` by default). If this volume isn't persisted between runs, the tracker resets and images are re-uploaded.
Make sure `/app/.if_cache` is mounted to a persistent host path.
---
## Re-uploading a specific person
To clear the upload history for one person and start fresh:
```env
RESET_PERSON=John
```
Remove this after one run — it clears the history and then processes normally.
---
## Image quality issues
- **Too blurry**: Lower `BLUR_THRESHOLD` (default 100) — e.g. `50` accepts more blur
- **Face too small**: Lower `MIN_FACE_WIDTH` (default 50px)
- **Low confidence detections included**: Raise `MIN_CONFIDENCE` (default 0.7)
- **Rejected images being re-tried**: Set `RETRY_REJECTED=true` for one run