WIP: backend Windows-native dev/test setup

[derneuere]

WIP / draft. Opening for visibility and discussion. Backend-only, additive — no changes to runtime/product code or the Linux/Docker path. CI is path-filtered, so this only touches the backend pipeline.

What

Make the backend installable and testable natively on Windows (Python 3.11, in-memory SQLite), without Docker. Every "hostile" dependency installs from prebuilt wheels; the few that need an external binary or a C++ compiler are handled by a setup script.

Why

Lets contributors on Windows run the backend test suite without a container. Verified end-to-end: a clean install of requirements.windows.txt into a fresh venv + manage.py test api.tests →

Ran 1363 tests in 221s — 1330 passed (6 failures, 8 errors, 19 skipped)

The ~14 failures are environmental, not install/import failures: Windows case-insensitive filesystem (e.g. IMG_002.mov vs .MOV), path separators, timestamp-tie ordering flakes, and exiftool/mock test scaffolding. Open to fixing/marking those separately if wanted.

How each hostile dependency was solved (verified at pinned versions on py3.11/win_amd64)

Package	Approach
pyvips	pyvips[binary] — bundles libvips, no system install
python-magic	python-magic-bin + a venv .pth shim. Git-for-Windows' MSYS msys-magic-1.dll on PATH otherwise segfaults CPython on import magic; the shim prepends the bundled libmagic dir.
Wand	winget ImageMagick.ImageMagick (the inno DLL build — the default ImageMagick.Q16-HDRI msix ships no MagickWand DLLs)
faiss-cpu, onnxruntime, sentencepiece, gevent, hdbscan	plain prebuilt cp311 wheels
torch stack (torch/sentence_transformers/transformers/timm)	default PyPI CPU wheel (torch 2.12.1+cpu)
llama-cpp-python	maintainer CPU wheel index via --extra-index-url
insightface	no wheel — compiles from sdist, needs MSVC v143 (VS 2022 / Build Tools)
PyExifTool	pip + winget OliverBetz.ExifTool (runtime binary; migration 0009 starts it)
psycopg	psycopg[binary] (no system libpq on Windows)
gunicorn	installs but can't serve on Windows (no fcntl); use manage.py runserver

Files

Native path (primary)

• requirements.windows.txt — DRY: -r requirements.txt + -r requirements.dev.txt + only the Windows variants
• scripts/setup_windows.ps1 — venv + pip + winget binaries + libmagic shim, one command
• scripts/run_tests_windows.ps1 — native runner (real deps, SQLite, exiftool on PATH)

Lightweight fallback (no native deps / no C++ compiler)

• requirements.windows-test.txt + librephotos/settings/_win_stubs.py + test_windows.py — stub the native/ML modules via a meta-path finder so pure-Python logic tests run

Docs/meta

• CLAUDE.md (both paths documented), .gitignore (.venv*/, .testtmp/)

Open questions for review

• Worth committing the libmagic shim as a real Windows startup hook in product code (so runserver works without the venv .pth), or keep it dev-only?
• Keep both the native and stub paths, or just the native one?

🤖 Generated with Claude Code