7.1 KiB
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 (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) :
# --- 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_DSNest lu au runtime par les conteneurs backend (pas besoin de rebuild).VITE_SENTRY_DSNest injecté au build deprediqo-web— un rebuild du frontend est obligatoire après modification.
1.3 Rebuild & redémarrage
# 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) :
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 :
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).
# 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 :
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 :
docker compose up -d backend
2.3 Vérification
1. Santé clamd
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)
# 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 :
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 |