# Setup local

# Setup local

> _Dernière mise à jour : 2026-05-10_

## Étapes

```bash
# 1. Cloner
git clone <gitea-url>/boardgame-referee.git
cd boardgame-referee

# 2. Configurer l'env
cp .env.example .env
# Éditer .env (cf. variables-environnement.md pour la liste complète)

# 3. Installer les deps
npm install
cd frontend && npm install && cd ..

# 4. Lancer Qdrant en dev
docker compose -f docker-compose.dev.yml up -d qdrant

# 5. Migrer la BDD
npm run db:migrate

# 6. Backend en dev
npm run dev
# (tsx watch src/index.ts)

# 7. Frontend en dev (autre terminal)
cd frontend
npm run dev
# (vite dev server :5173 + proxy /api → :3000)
```

## URLs en dev

- Backend Hono : <http://localhost:3000>
- Frontend Vite : <http://localhost:5173>
- Qdrant : <http://localhost:6333>

Le frontend Vite proxifie `/api/*` vers `:3000` (config dans `frontend/vite.config.ts`).

## Variables minimales pour démarrer

```env
# Backend
PORT=3000
DB_PATH=./data/database.db
PDF_DIR=./pdfs
COOKIE_SECRET=<32+ chars hex, ex: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))">

# Services externes (en local pointant sur l'Unraid)
QDRANT_URL=http://192.168.10.100:6333
TEI_URL=http://192.168.10.100:8099
TEI_RERANKER_URL=http://192.168.10.100:8990

# Claude (mode local sur ta machine, ou SSH en prod)
CLAUDE_USE_LOCAL=true
CLAUDE_LOCAL_BIN=claude
CLAUDE_LOCAL_WORKDIR=/home/thymon/workdir-claude

# Premier admin
FIRST_ADMIN_USERNAME=thymon
FIRST_ADMIN_PASSWORD=<>=8 chars>
```

## Tester

```bash
# Backend health
curl http://localhost:3000/api/health

# Backend tests unitaires (Vitest)
npm test

# Frontend tests
cd frontend && npm test

# Type-check (équivalent CI)
npm run build           # backend (tsc)
cd frontend && npm run build  # frontend (vue-tsc --build + vite build)
```

## Commandes NPM essentielles

| Commande | Usage |
|---|---|
| `npm run dev` | Backend dev hot-reload (`tsx watch`) |
| `npm run build` | Compile TypeScript backend → `dist/` |
| `npm start` | Lance le backend compilé (`node dist/index.js`) |
| `npm test` / `npm run test:watch` | Vitest |
| `npm run db:generate` | Génère une migration Drizzle après modif `src/schema.ts` |
| `npm run db:migrate` | Applique les migrations |
| `npm run debug:question -- --id <questionId>` | CLI lecture seule pour relire les diagnostics d'une question |
| `npm run eval` | Banc d'éval RAG (questions de test + judge Haiku) |

Pour les commandes TCG (cartes / méta), cf. la section `tcg-integrations/`.

## Trois pièges à éviter

1. **`vue-tsc --noEmit` pour le type-check** : c'est `vue-tsc --build` qui passe en CI, pas `--noEmit`. Toujours tester avec `npm run build` avant de push.
2. **Style scoped vs Tailwind hidden** : un `display: flex` en scoped écrase le `hidden lg:flex` du template. Préférer Tailwind utilities partout.
3. **`z.coerce.boolean()` dans config.ts** : `Boolean("false") === true` en JS — utiliser le helper `envBool()` défini en haut de `src/config.ts`.