Skip to content

Setup

Jump to bottom
sudolulo edited this page Jun 12, 2026 · 11 revisions

Setup Guide

Prerequisites

  • Immich v1.106+ with face recognition enabled and people tagged
  • Frigate 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. 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. Set a container memory limit of at least 2 GB (mem_limit: 2g) — the embedding models need roughly 1–1.5 GB and thumbnails are batched, but without a limit an OOM kill will restart the container mid-run.

4. Deploy with Docker Compose

Copy compose.yml and .env.example to a directory on your host:

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:

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 point to directories on your host where models, cache, and output crops should be stored:

volumes:
  - /your/path/to/models:/models
  - /your/path/to/cache:/app/.if_cache
  - /your/path/to/output:/app/frigate_train

These directories will be created automatically by Docker if they don't exist.

Start it:

docker compose up -d

Logs:

docker compose logs -f winnow

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.

6. Scheduling

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

In scheduled mode the process (and loaded models) stays resident between runs, so each subsequent run starts immediately without re-loading models.

GPU passthrough

To enable GPU acceleration, include the deploy block in compose.yml (already present in the example) and ensure the NVIDIA container toolkit is installed on your host:

# Verify GPU is accessible to Docker
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, 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:

docker exec winnow cat /app/winnow.log

Clone this wiki locally