# 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://@.ingest.sentry.io/ 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://@.ingest.sentry.io/ 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`** (opt-in). ```bash # Démarrer ClamAV + mettre à jour le backend docker compose --profile clamav up -d clamav docker compose up -d backend ``` 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) ### 2.2 Variables d’environnement Dans le `.env` racine : ```env CLAMAV_ENABLED=true CLAMAV_HOST=clamav CLAMAV_PORT=3310 CLAMAV_TIMEOUT_MS=60000 ``` `CLAMAV_HOST=clamav` correspond au **nom du service** Docker sur `prediqo-net`. Puis redémarrez l’API : ```bash docker compose up -d backend ``` ### 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)://: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) [ ] docker compose --profile clamav up -d clamav [ ] CLAMAV_ENABLED=true, CLAMAV_HOST=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 |