games_app/deploy/PRODUCTION_SENTRY_CLAMAV.md

7.9 KiB
Raw Blame History

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_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

# 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.

Les commandes VPS Phase B démarrent déjà ClamAV avec la stack :

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.) :

# 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 :

sudo npm run phase-b:up:https

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)
[ ] `.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