Prérequis

Prérequis
Dernière mise à jour : 2026-05-10
Outils CLI
Outil
Version
Notes
Node.js
22.x (
node:22-bookworm-slim en CI/prod)
Pas Alpine — 
better-sqlite3 n'a pas de prebuilt musl
npm
10.x (vient avec Node 22)
Docker
24+
Pour 
docker compose up qdrant en dev
Docker Compose v2
(intégré à Docker)
poppler-utils
Récent
Fournit 
pdftoppm (rendu PDF→PNG 300 DPI)
tesseract-ocr
5.x
Pour OCR auto des PDFs scannés
tesseract-ocr-fra + 
tesseract-ocr-eng
Packs langues
git
Récent
Installation system deps (Ubuntu/Debian)
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-fra tesseract-ocr-eng
Pour ajouter d'autres langues d'OCR :
sudo apt-get install -y tesseract-ocr-ita tesseract-ocr-deu
# Puis dans .env :
# OCR_LANGUAGES=fra+eng+ita+deu
Sans ces outils, pdfjs-dist continuera à extraire les PDFs natifs, mais (1) aucun PNG ne sera généré (échec non-fatal logué 
warn), (2) un PDF scanné finira avec 0 chunks.
Services externes (à avoir tournants)
Qdrant (vector DB)
Port 6333
Dev local : 
docker compose -f docker-compose.dev.yml up -d qdrant (depuis la racine du projet)
Prod : container Qdrant sur Unraid au même endroit (volume 
/mnt/user/appdata/boardgame-referee/qdrant)
TEI bge-m3 (embeddings)
Port 8099 (custom — par défaut TEI utiliserait 80)
Lance le service Unraid 
text-embeddings-inference (template XML dans 
unraid/)
En dev local sans GPU : faisable sur CPU mais lent — préférer pointer 
TEI_URL vers l'instance Unraid via SSH tunnel ou exposition LAN
TEI Reranker bge-v2-m3
Port 8990 (8090 était déjà pris)
Service Unraid 
text-embeddings-reranker
VM oracle (Claude Code CLI)
VM avec compte SSH 
oracle configuré (cf. 
securite/ssh-oracle.md)
Claude Code installé dans 
/home/oracle/.claude/
Credentials Anthropic dans 
/home/oracle/.claude/.credentials.json
Wrapper 
/home/oracle/bin/oracle-claude.sh (ForceCommand)
Optionnel
SMTP : si tu veux les notifications de register et le password reset par mail. Sinon 
SMTP_HOST vide → désactivé silencieusement.
BGG API token : pour le forum sync. Optionnel, l'API publique fonctionne sans (rate-limit moins strict avec token).
Cas spécial : dev sur la machine qui héberge Claude
Si tu lances le backend sur la même machine que le binaire 
claude (ex. ton laptop dev), le SSH boucle sur lui-même. Active le mode local :
CLAUDE_USE_LOCAL=true
CLAUDE_LOCAL_BIN=claude
CLAUDE_LOCAL_WORKDIR=/path/to/workdir/with/CLAUDE.md
Les vars 
CLAUDE_SSH_* sont alors ignorées (mais peuvent rester en place). Ne jamais activer en prod : le container Docker n'a pas accès à 
claude localement.