217 lines
6.9 KiB
Markdown
217 lines
6.9 KiB
Markdown
# 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`** (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`.
|
||
|
||
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 |
|