games_app/deploy/PRODUCTION_SENTRY_CLAMAV.md

232 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Production — Sentry & ClamAV (Docker)
Guide pour activer l’observabilité (Sentry) et le scan antivirus (ClamAV/clamd) sur le stack Prediqo déployé avec Docker Compose.
---
## Prérequis
- Stack Prediqo déjà déployé (`docker-compose.yml` à la racine)
- Fichier `.env` à la racine du dépôt (VPS) — **jamais commité**
- Accès admin au projet [sentry.io](https://sentry.io) (gratuit jusqu’à un certain volume)
---
## 1. Sentry
### 1.1 Créer les projets Sentry
Créez **deux projets** dans la même organisation Sentry :
| Projet | Plateforme | Usage |
|--------|------------|--------|
| `prediqo-api` | **Node.js** | Processus `backend`, `backend-ws`, `backend-engine`, `backend-worker-bets` |
| `prediqo-web` | **React** | Application `prediqo_web` (navigateur) |
Pour chaque projet : **Settings → Client Keys (DSN)** — copiez le DSN (`https://…@….ingest.sentry.io/…`).
### 1.2 Variables d’environnement
Ajoutez dans le `.env` **à la racine** (VPS) :
```env
# --- Sentry (backend — tous les conteneurs Node partagent le même DSN API) ---
SENTRY_DSN=https://<public_key>@<org>.ingest.sentry.io/<project_id>
SENTRY_TRACES_SAMPLE_RATE=0.1
# Optionnel : version déployée (releases Sentry)
SENTRY_RELEASE=prediqo@1.0.0
# --- Sentry (frontend — figé au BUILD Docker) ---
VITE_SENTRY_DSN=https://<public_key>@<org>.ingest.sentry.io/<web_project_id>
VITE_SENTRY_TRACES_SAMPLE_RATE=0.1
```
**Important :**
- `SENTRY_DSN` est lu **au runtime** par les conteneurs backend (pas besoin de rebuild).
- `VITE_SENTRY_DSN` est injecté **au build** de `prediqo-web` — un **rebuild** du frontend est obligatoire après modification.
### 1.3 Rebuild & redémarrage
```bash
# Depuis la racine du dépôt sur le VPS
docker compose build prediqo-web
docker compose up -d backend backend-ws backend-engine backend-worker-bets prediqo-web
```
Ou via les scripts npm du projet (selon votre profil HTTP/HTTPS) :
```bash
npm run phase-b:up # HTTP
# ou
npm run phase-b:up:https # HTTPS
```
### 1.4 Vérification
**Backend :** provoquez une erreur 5xx (ex. endpoint inexistant côté admin) ou consultez les logs :
```bash
docker compose logs backend | tail -50
```
Dans Sentry → projet `prediqo-api` → **Issues**, l’événement doit apparaître sous quelques secondes.
**Frontend :** ouvrez la console navigateur, vérifiez l’absence d’erreur Sentry au chargement. Une erreur React non gérée doit remonter dans le projet `prediqo-web`.
### 1.5 Bonnes pratiques production
| Paramètre | Recommandation |
|-----------|----------------|
| `SENTRY_TRACES_SAMPLE_RATE` | `0.05`–`0.1` en prod (coût / volume) |
| `VITE_SENTRY_TRACES_SAMPLE_RATE` | `0.05`–`0.1` |
| `SENTRY_RELEASE` | Tag git (`prediqo@$(git rev-parse --short HEAD)`) à chaque déploiement |
| Environnements | Sentry distingue automatiquement via `NODE_ENV` / `import.meta.env.MODE` |
| Alertes | Configurez des alertes Sentry (email/Slack) sur les nouvelles issues **fatal** |
Les messages d’erreur **4xx métier** (login invalide, validation) ne sont **pas** envoyés à Sentry — seules les erreurs **5xx** côté API sont capturées par le middleware centralisé.
---
## 2. ClamAV (clamd)
Le backend scanne les uploads **FAQ** et **Support** via le protocole **INSTREAM** de clamd (port TCP 3310), après validation des magic bytes.
### 2.1 Activer le service Docker
Le service `clamav` est défini dans `docker-compose.yml` avec le profil **`clamav`**.
Les commandes VPS Phase B démarrent **déjà** ClamAV avec la stack :
```bash
sudo npm run phase-b:up:https # HTTPS + clamav
sudo npm run phase-b:up # HTTP + clamav
sudo npm run phase-b:up:ssl # SSL + clamav
sudo npm run phase-b:init:https # migrate + HTTPS + clamav
```
Pas besoin d’une commande ClamAV séparée.
Le conteneur `clamav` :
- Télécharge les signatures virales au premier démarrage (`freshclam`) — **2 à 10 minutes**
- Expose le port **3310** uniquement sur le réseau interne `prediqo-net` (pas exposé sur l’hôte)
> Au premier boot, attendez que clamd soit prêt avant de tester les uploads (`docker compose logs -f clamav`).
### 2.2 Variables d’environnement (`.env` VPS)
À ajouter / vérifier dans le `.env` **racine** du VPS (même fichier que `DATABASE_URL`, `JWT_SECRET`, etc.) :
```env
# ClamAV — scan antivirus des uploads Support / FAQ
CLAMAV_ENABLED=true
CLAMAV_HOST=clamav
CLAMAV_PORT=3310
CLAMAV_TIMEOUT_MS=60000
```
| Variable | Valeur VPS | Pourquoi |
|----------|------------|----------|
| `CLAMAV_ENABLED` | `true` | Force le scan (sinon déjà on si `NODE_ENV=production`) |
| `CLAMAV_HOST` | `clamav` | Nom du **service Docker** sur `prediqo-net` (pas `127.0.0.1`) |
| `CLAMAV_PORT` | `3310` | Port clamd interne |
| `CLAMAV_TIMEOUT_MS` | `60000` | Délai confortable pendant le 1er `freshclam` |
Puis un seul redémarrage de stack :
```bash
sudo npm run phase-b:up:https
```
### 2.3 Vérification
**1. Santé clamd**
```bash
docker compose exec clamav clamdscan --version
docker compose logs clamav | tail -30
```
Attendez le message indiquant que `clamd` est prêt avant de tester les uploads.
**2. Test EICAR (fichier test inoffensif)**
```bash
# Créer un fichier EICAR
echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > /tmp/eicar.txt
# Scan direct via clamd dans le conteneur
docker compose exec clamav clamdscan /tmp/eicar.txt
# Attendu : Eicar-Signature FOUND
```
**3. Test via l’API**
Tentez d’uploader `eicar.txt` via l’interface Support ou FAQ admin. Réponse attendue : **HTTP 422** avec message du type `File failed virus scan`. Le fichier est supprimé du disque.
### 2.4 Sans ClamAV
Si `CLAMAV_ENABLED` est absent ou `false` :
- Aucun scan antivirus
- Les magic bytes restent actifs (défense de base)
Recommandé en **dev local** ; en **production**, activez ClamAV dès que des uploads utilisateurs sont possibles.
### 2.5 Dépannage
| Symptôme | Cause probable | Action |
|----------|----------------|--------|
| `Virus scan unavailable: connect ECONNREFUSED` | clamd pas démarré ou DB pas prête | `docker compose logs clamav`, attendre fin de `freshclam` |
| Uploads lents | Fichiers volumineux (jusqu’à 10 Mo FAQ) | Augmenter `CLAMAV_TIMEOUT_MS` |
| Signatures obsolètes | Pas de mise à jour auto | Redémarrer `clamav` périodiquement ou cron `freshclam` |
| `CLAMAV_HOST=127.0.0.1` dans Docker | Mauvais host | Utiliser `clamav` (nom du service), pas `localhost` |
---
## 3. WebSocket sécurité (rappel)
Les notifications admin temps réel utilisent `/ws/v1/security` sur le processus `backend-ws`. Nginx route déjà tout le préfixe `/ws/` vers `backend-ws:4001` (interne Docker).
Le frontend résout l’URL en **same-origin** (`ws(s)://<hôte>:9080|9443/ws/v1/security`) — **ne pas** exposer ni bakee `ws://…:4001` en production (timeout navigateur).
Vérifiez dans `.env` :
```env
WS_ENABLED=true
VITE_WS_ENABLED=true
```
Le canal sécurité fonctionne dès que Redis et `backend-ws` tournent — indépendamment de Sentry/ClamAV.
---
## 4. Checklist déploiement
```
[ ] Projets Sentry créés (API + Web)
[ ] SENTRY_DSN dans .env racine
[ ] VITE_SENTRY_DSN dans .env racine
[ ] Rebuild prediqo-web après ajout VITE_SENTRY_DSN
[ ] Test issue Sentry backend (5xx)
[ ] `.env` VPS : CLAMAV_ENABLED=true, CLAMAV_HOST=clamav, CLAMAV_PORT=3310, CLAMAV_TIMEOUT_MS=60000
[ ] `sudo npm run phase-b:up:https` (démarre aussi le profil clamav)
[ ] Redémarrage backend
[ ] Test upload EICAR → 422
[ ] npm run db:migrate (si pas fait depuis P4/P5)
```
---
## 5. Résumé des fichiers concernés
| Fichier | Rôle |
|---------|------|
| `docker-compose.yml` | Service `clamav` (profil `clamav`), env Sentry/ClamAV sur `backend-common` |
| `.env` (racine, VPS) | Secrets et flags production |
| `backend/src/observability/sentry.ts` | Init Sentry API/WS |
| `backend/src/services/virusScanService.ts` | Client clamd INSTREAM |
| `prediqo_web/Dockerfile` | Build args `VITE_SENTRY_*` |
| `prediqo_web/src/shared/observability/sentry.ts` | Init Sentry navigateur |