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>
2026-06-12 01:26:24 +00:00
parent eea7baa19f
commit b7dc87b05b
7 changed files with 280 additions and 5 deletions
@@ -0,0 +1,88 @@
+# Setup Guide
+
+## Prerequisites
+
+- [Immich](https://immich.app) v1.106+ with face recognition enabled and people tagged
+- [Frigate](https://frigate.video) v0.16+ (face mode only)
+- Docker with the NVIDIA container toolkit (optional but strongly recommended)
+
+---
+
+## 1. Get your Immich API key
+
+1. Open Immich → **Account Settings** → **API Keys**
+2. Click **New API Key**, give it a name (e.g. `winnow`), copy the key
+
+---
+
+## 2. Get your Frigate URL
+
+This is the base URL of your Frigate instance, e.g. `http://192.168.1.10:5000`. Only needed for face mode — omit it entirely if you're using object mode.
+
+---
+
+## 3. Deploy with Docker Compose
+
+Copy [`compose.yml`](../compose.yml) and [`.env.example`](../.env.example) to a directory on your host:
+
+```bash
+mkdir winnow && cd winnow
+curl -O https://raw.githubusercontent.com/sudolulo/winnow/main/compose.yml
+curl -O https://raw.githubusercontent.com/sudolulo/winnow/main/.env.example
+cp .env.example .env
+```
+
+Edit `.env` with your values:
+
+```bash
+IMMICH_URL=http://192.168.1.10:2283
+API_KEY=your-immich-api-key
+FRIGATE_URL=http://192.168.1.10:5000
+```
+
+Edit the volume paths in `compose.yml` to match your storage layout (replace `/mnt/<pool>` with your actual path).
+
+Start it:
+
+```bash
+docker compose up -d
+```
+
+Logs:
+
+```bash
+docker compose logs -f winnow
+```
+
+---
+
+## 4. 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.
+
+---
+
+## 5. Scheduling
+
+Set `CRON_SCHEDULE` in your `.env` to keep winnow running on a schedule:
+
+```
+CRON_SCHEDULE=0 3 * * 0   # Every Sunday at 3 AM
+```
+
+Without `CRON_SCHEDULE`, the container runs once and exits.
+
+---
+
+## TrueNAS Scale
+
+The included `compose.yml` uses TrueNAS-style volume paths. Replace `<pool>` with your pool name:
+
+```yaml
+volumes:
+  - /mnt/tank/winnow/models:/models
+  - /mnt/tank/winnow/embeddings:/app/.if_cache
+  - /mnt/tank/winnow/output:/app/frigate_train
+```
+
+GPU passthrough on TrueNAS requires the NVIDIA app to be installed from the TrueNAS catalog and the `deploy.resources.reservations.devices` block in `compose.yml` (already included).