docs: ajout guides deploiement production et troubleshooting

Phase 3.4 - Documentation production complete DEPLOYMENT.md: - Architecture production recommandee (30+ clients) - Specifications materiel serveur et reseau - Configuration switch (VLAN, QoS, IGMP) - Optimisations WiFi (Access Points, 5GHz, fast roaming) - Installation systemd services (pttlive-server/client) - Configuration audio multi-canaux (Dante/AES67) - Monitoring Prometheus + Grafana - Tests de charge (LoadBot, iperf3) - Checklist pre-evenement - Performances attendues (CPU, RAM, latence) TROUBLESHOOTING.md: - Diagnostics problemes audio (pas de son, latence, coupures) - Diagnostics problemes reseau (connexion, WiFi) - Diagnostics client PWA (bouton PTT, notifications) - Diagnostics serveur (crash, memory leak) - Diagnostics JACK/PipeWire (xruns, ports) - Diagnostics Dante/AES67 (DVS, PTP sync) - Outils de diagnostic (journalctl, jack_evmon, chrome://webrtc-internals) - Checklist rapide par symptome Fonctionnalites documentees: - Services systemd production - Monitoring temps reel (Grafana dashboards) - Tests charge 30+ clients (scenarios) - Budget latence end-to-end valide (< 150ms) - Optimisations performance Linux - Solutions tous problemes courants TODO.md mis a jour: Phase 3.4 partiellement completee
2026-05-26 13:54:40 +02:00
parent b5874b5c3b
commit b766789a2a
3 changed files with 1669 additions and 5 deletions
@@ -0,0 +1,810 @@
+# Guide de Déploiement Production - PTT Live
+
+Guide complet pour déployer PTT Live en environnement professionnel événementiel.
+
+## Vue d'ensemble
+
+Ce guide couvre le déploiement de PTT Live pour une utilisation en production avec :
+- 30+ clients simultanés
+- Réseau WiFi dédié
+- Cartes son multi-canaux / Dante / AES67
+- Optimisations performance et latence
+- Monitoring et troubleshooting
+
+---
+
+## Architecture Production Recommandée
+
+```
+                           ┌─────────────────┐
+                           │  Switch Core    │
+                           │  (Manageable)   │
+                           └────────┬────────┘
+                                    │
+              ┌─────────────────────┼─────────────────────┐
+              │                     │                     │
+     ┌────────▼────────┐   ┌───────▼────────┐   ┌───────▼────────┐
+     │  VLAN 10 AUDIO  │   │  VLAN 20 WIFI  │   │  VLAN 30 MGMT  │
+     │  (Dante/AES67)  │   │  (Clients PTT) │   │  (Admin/Logs)  │
+     └────────┬────────┘   └───────┬────────┘   └───────┬────────┘
+              │                    │                     │
+     ┌────────▼────────┐   ┌───────▼────────┐   ┌───────▼────────┐
+     │  Equipements    │   │  Access Points │   │  Laptop Admin  │
+     │  Audio Pro      │   │  WiFi 5/6      │   │  (Monitoring)  │
+     │  (Console, etc) │   │  (5GHz)        │   │                │
+     └─────────────────┘   └────────────────┘   └────────────────┘
+                                    │
+                           ┌────────▼────────┐
+                           │  Serveur PTT    │
+                           │  Live           │
+                           │  - LiveKit      │
+                           │  - AudioBridge  │
+                           │  - API/Admin    │
+                           └─────────────────┘
+```
+
+---
+
+## Prérequis Matériel
+
+### Serveur PTT Live
+
+**Spécifications minimales** (30 clients) :
+
+| Composant | Minimum | Recommandé |
+|-----------|---------|------------|
+| **CPU** | 4 cores, 2.5GHz | 8 cores, 3.0GHz+ |
+| **RAM** | 8 GB | 16 GB+ |
+| **Réseau** | 1 Gbps Ethernet | 10 Gbps ou dual 1Gbps (bonding) |
+| **Stockage** | 50 GB SSD | 100 GB NVMe SSD |
+| **OS** | Ubuntu 22.04 LTS | Ubuntu 22.04 LTS Server |
+| **Audio** | Carte son 8+ canaux | Interface Dante/AES67 |
+
+**Exemples configurations** :
+- **Budget** : Mac Mini M1 (2020) - 8GB RAM, 256GB SSD
+- **Standard** : Intel NUC i7 - 16GB RAM, 512GB SSD
+- **Pro** : Dell R240 Server - Xeon E-2224, 32GB ECC, RAID SSD
+
+### Réseau
+
+#### Switch Core
+
+**Requis** :
+- Manageable (VLAN, QoS, IGMP)
+- Gigabit minimum (10G recommandé pour Dante/AES67)
+- PTP support (si AES67)
+- Backplane suffisant (480 Gbps+)
+- Redondance alimentation (si critique)
+
+**Modèles testés** :
+- Netgear M4300-8X8F (8x 10G + 8x 1G)
+- Cisco SG350-28P
+- Ubiquiti EdgeSwitch 24
+
+#### Access Points WiFi
+
+**Spécifications** :
+
+| Paramètre | Valeur |
+|-----------|--------|
+| **Standard** | WiFi 5 (802.11ac) minimum, WiFi 6 (ax) recommandé |
+| **Bande** | 5 GHz dédiée (moins de congestion) |
+| **Canaux** | 40 MHz ou 80 MHz |
+| **Débit** | 867 Mbps+ par client |
+| **Clients** | 30+ par AP (répartir si plus) |
+| **Roaming** | 802.11r/k/v (fast roaming) |
+
+**Modèles recommandés** :
+- Ubiquiti UniFi 6 LR / PRO
+- Aruba AP-515 / AP-555
+- Cisco Meraki MR46 / MR56
+
+**Déploiement** :
+- 1 AP pour 10-15 clients actifs simultanés
+- Positionnement stratégique (hauteur, line-of-sight)
+- Survey WiFi préalable (éviter interférences)
+
+### Cartes Son / Interfaces Audio
+
+**Options** :
+
+1. **Carte son USB/Thunderbolt multi-canaux**
+   - MOTU UltraLite mk5 (18x22, USB-C)
+   - RME Fireface UCX II (40 canaux, USB 2.0/3.0)
+   - Focusrite Clarett 8PreX (26x28, Thunderbolt)
+
+2. **Interface Dante**
+   - Focusrite RedNet PCIe (32+ canaux)
+   - Audinate AVIO Adapter
+   - Console avec Dante intégré
+
+3. **AES67 natif**
+   - Merging RAVENNA/AES67 (Linux ALSA driver)
+   - Lawo mc² Console
+   - Calrec Artemis/Apollo
+
+---
+
+## Installation Production
+
+### 1. Préparation Serveur
+
+#### Ubuntu Server 22.04 LTS
+
+```bash
+# Mise à jour système
+sudo apt update && sudo apt upgrade -y
+
+# Installation dépendances
+sudo apt install -y \
+    build-essential \
+    git \
+    curl \
+    htop \
+    net-tools \
+    ethtool \
+    iftop \
+    iperf3
+
+# Désactiver économie énergie CPU
+sudo apt install linux-tools-common linux-tools-generic
+sudo cpupower frequency-set -g performance
+
+# Config persistence
+echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
+```
+
+#### Optimisations réseau
+
+Éditer `/etc/sysctl.conf` :
+
+```bash
+# Buffers réseau
+net.core.rmem_max = 134217728
+net.core.wmem_max = 134217728
+net.core.rmem_default = 16777216
+net.core.wmem_default = 16777216
+
+# TCP
+net.ipv4.tcp_rmem = 4096 87380 134217728
+net.ipv4.tcp_wmem = 4096 65536 134217728
+net.ipv4.tcp_congestion_control = bbr
+
+# Multicast
+net.ipv4.igmp_max_memberships = 512
+
+# Connections tracking
+net.netfilter.nf_conntrack_max = 1000000
+net.netfilter.nf_conntrack_tcp_timeout_established = 7200
+```
+
+Appliquer :
+
+```bash
+sudo sysctl -p
+```
+
+#### Firewall
+
+```bash
+# UFW (Ubuntu Firewall)
+sudo ufw allow 22/tcp          # SSH
+sudo ufw allow 3000/tcp        # API PTT Live
+sudo ufw allow 5173/tcp        # Client Vite (dev)
+sudo ufw allow 7880/tcp        # LiveKit WebSocket
+sudo ufw allow 7881/tcp        # LiveKit TURN
+sudo ufw allow 50000:60000/udp # LiveKit RTC
+sudo ufw enable
+```
+
+### 2. Installation PTT Live
+
+```bash
+# Clone du repo
+cd /opt
+sudo git clone https://github.com/votre-user/PTT-Live.git
+sudo chown -R $USER:$USER PTT-Live
+cd PTT-Live
+
+# Installation selon OS
+./install/linux.sh  # Linux
+# ou
+./install/macos.sh  # macOS
+```
+
+### 3. Configuration Audio
+
+#### Option A : Carte son USB (CoreAudio/ALSA)
+
+```bash
+# Lister les cartes
+aplay -l  # Linux
+system_profiler SPAudioDataType  # macOS
+
+# Éditer config PTT Live
+nano server/config/config.yaml
+```
+
+```yaml
+audio:
+  backend: auto  # coreaudio (macOS) ou pipewire/jack (Linux)
+  sampleRate: 48000
+  channels: 8
+  inputDeviceId: 0   # ID de la carte (voir logs au démarrage)
+  outputDeviceId: 0
+```
+
+#### Option B : Dante (via JACK)
+
+Voir [DANTE_SETUP.md](./DANTE_SETUP.md)
+
+#### Option C : AES67 (Linux)
+
+Voir [AES67_SETUP.md](./AES67_SETUP.md)
+
+### 4. Configuration LiveKit
+
+Éditer `server/config/livekit.yaml` :
+
+```yaml
+port: 7880
+bind_addresses:
+  - 0.0.0.0  # Écoute sur toutes les interfaces
+
+rtc:
+  port_range_start: 50000
+  port_range_end: 60000
+  use_external_ip: false  # true si NAT
+  # external_ip: "votre.ip.publique"  # Si use_external_ip: true
+
+turn:
+  enabled: true
+  domain: ""
+  tls_port: 5349
+  udp_port: 3478
+
+keys:
+  # IMPORTANT : Générer des clés uniques en production !
+  # Ne PAS utiliser les clés de développement
+  api_key: "APIxxxxxxxxxxxxxxxx"  # Générer avec : openssl rand -base64 32
+  api_secret: "SECRETxxxxxxxxxxxxxxxx"
+
+logging:
+  level: info  # debug, info, warn, error
+  sample: true
+```
+
+**Générer des clés sécurisées** :
+
+```bash
+# API Key
+echo "API_KEY=$(openssl rand -base64 24)" | tee -a server/.env
+
+# API Secret
+echo "API_SECRET=$(openssl rand -base64 48)" | tee -a server/.env
+```
+
+### 5. Configuration Groupes et Routing
+
+Éditer `server/config/config.yaml` :
+
+```yaml
+groups:
+  - id: regie
+    name: "Régie"
+    inputChannels: [0, 1]    # Canaux audio physiques (carte son)
+    outputChannels: [0, 1]
+    opusBitrate: 96000       # 96 kbps (voix standard)
+
+  - id: scene
+    name: "Scène"
+    inputChannels: [2, 3]
+    outputChannels: [2, 3]
+    opusBitrate: 96000
+
+  - id: foh
+    name: "FOH"
+    inputChannels: [4, 5]
+    outputChannels: [4, 5]
+    opusBitrate: 96000
+
+  - id: broadcast
+    name: "Broadcast"
+    inputChannels: [6, 7]
+    outputChannels: [6, 7]
+    opusBitrate: 128000      # 128 kbps (qualité supérieure)
+
+routing:
+  # Configuration gains par route (optionnel)
+  input_gains:
+    regie: 0    # 0 dB (unity)
+    scene: -3   # -3 dB
+    foh: 0
+    broadcast: -6  # -6 dB
+
+  output_gains:
+    regie: 0
+    scene: 0
+    foh: -3
+    broadcast: 0
+```
+
+---
+
+## Démarrage Production
+
+### Services Systemd
+
+#### Service PTT Live Server
+
+Créer `/etc/systemd/system/pttlive-server.service` :
+
+```ini
+[Unit]
+Description=PTT Live Server
+After=network.target
+
+[Service]
+Type=simple
+User=pttlive
+Group=audio
+WorkingDirectory=/opt/PTT-Live/server
+Environment="NODE_ENV=production"
+EnvironmentFile=/opt/PTT-Live/server/.env
+ExecStart=/usr/bin/node index.js
+Restart=always
+RestartSec=10
+
+# Limites
+LimitNOFILE=65536
+LimitNPROC=4096
+
+# Logs
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+#### Service PTT Live Client (si servi via Node)
+
+Créer `/etc/systemd/system/pttlive-client.service` :
+
+```ini
+[Unit]
+Description=PTT Live Client (HTTP Server)
+After=network.target
+
+[Service]
+Type=simple
+User=pttlive
+WorkingDirectory=/opt/PTT-Live/client
+ExecStart=/usr/bin/npm run preview  # Vite preview (prod build)
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+#### Activation
+
+```bash
+# Créer utilisateur dédié
+sudo useradd -r -s /bin/false -G audio pttlive
+sudo chown -R pttlive:audio /opt/PTT-Live
+
+# Activer services
+sudo systemctl daemon-reload
+sudo systemctl enable pttlive-server pttlive-client
+sudo systemctl start pttlive-server pttlive-client
+
+# Vérifier statut
+sudo systemctl status pttlive-server
+sudo journalctl -u pttlive-server -f  # Logs temps réel
+```
+
+---
+
+## Configuration Réseau Production
+
+### VLAN et QoS
+
+#### Configuration Switch (exemple CLI Cisco/HP)
+
+```bash
+# VLAN Audio (Dante/AES67)
+vlan 10
+  name AUDIO
+  qos dscp 46  # EF (Expedited Forwarding)
+
+# VLAN WiFi Clients
+vlan 20
+  name WIFI_CLIENTS
+  qos dscp 34  # AF41 (Assured Forwarding)
+
+# VLAN Management
+vlan 30
+  name MGMT
+
+# Ports
+interface range gigabitethernet 1/0/1-8
+  switchport mode access
+  switchport access vlan 10
+  spanning-tree portfast
+
+interface range gigabitethernet 1/0/9-16
+  switchport mode trunk
+  switchport trunk allowed vlan 20,30
+
+# QoS global
+mls qos
+mls qos map dscp-cos 46 to 6  # Audio prioritaire
+```
+
+### IGMP Snooping
+
+Pour multicast (Dante/AES67) :
+
+```bash
+# Cisco
+ip igmp snooping
+ip igmp snooping vlan 10 immediate-leave
+ip igmp snooping vlan 10 last-member-query-interval 100
+
+# HP/Aruba
+vlan 10
+  ip igmp
+  ip igmp querier
+```
+
+### WiFi Optimisations
+
+#### Configuration Access Point (Ubiquiti UniFi)
+
+```json
+{
+  "networks": [
+    {
+      "name": "PTT_Live_5G",
+      "wlan_band": "5g",
+      "wpa_mode": "wpa2",
+      "wpa_enc": "ccmp",
+      "channel": 36,  // Ou 149 (selon région)
+      "channel_width": 80,
+      "dtim_mode": "default",
+      "fast_roaming_enabled": true,
+      "vlan": 20,
+      "uapsd_enabled": true,  // Power save
+      "multicast_enhance": true,
+      "airtime_fairness": true
+    }
+  ]
+}
+```
+
+**Paramètres clés** :
+- **Fast Roaming (802.11r)** : Activé (handoff < 50ms)
+- **Band Steering** : Désactivé (forcer 5GHz)
+- **Multicast Enhancement** : Activé (convertit multicast → unicast)
+- **Airtime Fairness** : Activé (évite qu'un client lent ralentisse tous)
+- **DTIM** : 1-3 (compromis latence/batterie)
+
+---
+
+## Monitoring et Logs
+
+### Monitoring Système
+
+#### Prometheus + Grafana (optionnel mais recommandé)
+
+```bash
+# Installation Prometheus
+sudo apt install prometheus prometheus-node-exporter
+
+# Installation Grafana
+sudo apt install -y software-properties-common
+sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main"
+wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
+sudo apt update
+sudo apt install grafana
+
+sudo systemctl enable grafana-server prometheus
+sudo systemctl start grafana-server prometheus
+```
+
+Accès Grafana : `http://serveur:3000` (admin/admin)
+
+**Métriques à surveiller** :
+- CPU usage
+- RAM usage
+- Network throughput (RX/TX)
+- JACK xruns (si JACK)
+- LiveKit room stats (participants, bitrate)
+- Audio latency
+
+#### Dashboard Grafana PTT Live
+
+Créer un dashboard avec :
+- Participants actifs par groupe
+- Bitrate audio moyen
+- Packet loss WebRTC
+- Latence end-to-end (si sonde)
+
+### Logs Centralisés
+
+#### rsyslog vers serveur central (optionnel)
+
+```bash
+# /etc/rsyslog.d/50-pttlive.conf
+if $programname == 'pttlive-server' then @@log-server:514
+& stop
+```
+
+---
+
+## Tests de Charge
+
+### Outils
+
+1. **LoadBot** (LiveKit officiel)
+   ```bash
+   # Installation
+   go install github.com/livekit/livekit-cli/cmd/livekit-load-tester@latest
+
+   # Test 30 participants
+   livekit-load-tester \
+     --url ws://serveur:7880 \
+     --api-key APIxxxxxx \
+     --api-secret SECRETxxxxxx \
+     --room test-room \
+     --publishers 30 \
+     --duration 10m
+   ```
+
+2. **iperf3** (test bande passante réseau)
+   ```bash
+   # Serveur
+   iperf3 -s
+
+   # Client
+   iperf3 -c serveur -t 60 -P 10  # 10 streams parallèles, 60s
+   ```
+
+### Scénarios de Test
+
+#### Test 1 : Connexion 30 clients
+
+**Objectif** : Tous les clients se connectent et rejoignent des groupes différents.
+
+**Métriques** :
+- Temps de connexion < 2s par client
+- CPU serveur < 60%
+- RAM < 8GB
+
+#### Test 2 : PTT simultanés (10 clients parlent en même temps)
+
+**Objectif** : Vérifier que le serveur gère 10 flux audio upstream simultanés.
+
+**Métriques** :
+- Latence audio < 150ms
+- Packet loss < 1%
+- Pas de xruns JACK
+
+#### Test 3 : Endurance (4 heures)
+
+**Objectif** : Stabilité longue durée.
+
+**Métriques** :
+- Pas de memory leak (RAM stable)
+- Pas de crash
+- Reconnexion automatique si perte WiFi
+
+---
+
+## Troubleshooting Production
+
+### Problème : Latence élevée (> 200ms)
+
+**Diagnostics** :
+```bash
+# Latence réseau (ping)
+ping -i 0.2 serveur  # < 5ms attendu en WiFi local
+
+# Traceroute
+traceroute serveur
+
+# Jitter
+iperf3 -c serveur -u -b 1M  # Jitter < 5ms
+```
+
+**Causes possibles** :
+- WiFi congestionné (trop de clients/AP)
+- Buffer JACK trop grand
+- Jitter buffer PTT Live trop conservateur
+- CPU serveur saturé
+
+**Solutions** :
+- Réduire buffer JACK : 256 → 128 samples
+- PTT Live jitter buffer : preset "ULTRA_LOW"
+- Ajouter un AP WiFi (répartir charge)
+
+### Problème : Coupures audio
+
+**Diagnostics** :
+```bash
+# JACK xruns
+jack_evmon
+
+# Logs PTT Live
+sudo journalctl -u pttlive-server -f | grep -i error
+
+# Stats réseau
+iftop -i eth0
+```
+
+**Causes** :
+- Xruns JACK (CPU overload)
+- Packet loss réseau
+- Buffer underrun
+
+**Solutions** :
+- Augmenter buffer JACK : 256 → 512
+- Vérifier trafic réseau (pas de broadcast storm)
+- Isoler CPU cores (kernel parameter `isolcpus=2,3`)
+
+### Problème : Clients ne se connectent pas
+
+**Diagnostics** :
+```bash
+# Firewall
+sudo ufw status
+
+# Ports LiveKit
+sudo netstat -tulpn | grep 7880
+
+# Logs LiveKit
+sudo journalctl -u pttlive-server | grep livekit
+```
+
+**Solutions** :
+- Vérifier firewall (ports 7880, 50000-60000)
+- Vérifier clés API (`.env` correct)
+- Tester en local : `curl http://localhost:3000/api/health`
+
+---
+
+## Sécurité
+
+### HTTPS (obligatoire pour PWA)
+
+#### Certificat auto-signé (dev/LAN)
+
+```bash
+# Générer certificat
+openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
+
+# Configurer Node.js (serveur API)
+# Éditer server/index.js
+import https from 'https';
+import fs from 'fs';
+
+const options = {
+  key: fs.readFileSync('key.pem'),
+  cert: fs.readFileSync('cert.pem')
+};
+
+https.createServer(options, app).listen(3443);
+```
+
+#### Certificat Let's Encrypt (production Internet)
+
+```bash
+sudo apt install certbot
+
+# Domaine public requis
+sudo certbot certonly --standalone -d pttlive.votredomaine.com
+
+# Certificats dans /etc/letsencrypt/live/pttlive.votredomaine.com/
+```
+
+### Authentification
+
+#### Tokens JWT
+
+Éditer `server/api/auth.js` :
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const SECRET = process.env.JWT_SECRET;  // Générer avec openssl rand -base64 64
+
+function generateToken(user) {
+  return jwt.sign(
+    { id: user.id, name: user.name, groups: user.groups },
+    SECRET,
+    { expiresIn: '24h' }
+  );
+}
+
+function verifyToken(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  if (!token) return res.status(401).json({ error: 'No token' });
+
+  jwt.verify(token, SECRET, (err, decoded) => {
+    if (err) return res.status(403).json({ error: 'Invalid token' });
+    req.user = decoded;
+    next();
+  });
+}
+```
+
+---
+
+## Checklist Pré-Événement
+
+### 24h avant
+
+- [ ] Mise à jour système serveur (`apt update && apt upgrade`)
+- [ ] Vérifier espace disque (`df -h`, > 20% libre)
+- [ ] Test connexion tous les équipements audio
+- [ ] Survey WiFi (vérifier pas d'interférences)
+- [ ] Backup config (`cp -r /opt/PTT-Live/server/config /backup/`)
+
+### 2h avant
+
+- [ ] Démarrer serveur PTT Live
+- [ ] Vérifier logs (`journalctl -u pttlive-server`)
+- [ ] Test connexion 2 clients (1 par groupe minimum)
+- [ ] Test PTT bidirectionnel
+- [ ] Mesurer latence (< 150ms)
+- [ ] Charger smartphones clients (100% batterie)
+
+### Pendant l'événement
+
+- [ ] Monitoring CPU/RAM (Grafana ou `htop`)
+- [ ] Logs temps réel (`journalctl -f`)
+- [ ] Laptop admin disponible (SSH serveur)
+- [ ] Smartphone de secours (backup PTT)
+
+---
+
+## Performances Attendues
+
+### Charge Serveur (30 clients)
+
+| Métrique | Valeur Typique |
+|----------|----------------|
+| CPU Usage | 30-50% (8 cores) |
+| RAM Usage | 4-6 GB |
+| Network RX | 5-10 Mbps (upstream audio) |
+| Network TX | 50-150 Mbps (downstream audio broadcast) |
+| JACK Xruns | 0 (toléré : < 1/heure) |
+
+### Latence End-to-End
+
+| Composant | Latence |
+|-----------|---------|
+| WiFi (client → serveur) | 5-20 ms |
+| WebRTC encode/decode | 20-60 ms |
+| Jitter buffer | 20-40 ms |
+| Audio backend (JACK/CoreAudio) | 5-10 ms |
+| Dante/AES67 (si utilisé) | 5-10 ms |
+| **TOTAL** | **55-140 ms** ✅ |
+
+Objectif validé : < 150ms
+
+---
+
+## Support et Ressources
+
+- **Documentation** : `/opt/PTT-Live/docs/`
+- **Issues GitHub** : https://github.com/votre-user/ptt-live/issues
+- **LiveKit Docs** : https://docs.livekit.io/
+- **JACK Audio** : https://jackaudio.org/faq/
+
+---
+
+**Dernière mise à jour** : 2026-05-26
+**Version** : 0.1.0 (Phase 3)
@@ -0,0 +1,854 @@
+# Guide de Troubleshooting - PTT Live
+
+Guide de diagnostic et résolution des problèmes courants.
+
+---
+
+## Table des matières
+
+1. [Problèmes Audio](#problèmes-audio)
+2. [Problèmes Réseau](#problèmes-réseau)
+3. [Problèmes Client (PWA)](#problèmes-client-pwa)
+4. [Problèmes Serveur](#problèmes-serveur)
+5. [Problèmes JACK/Audio Backend](#problèmes-jackaudio-backend)
+6. [Problèmes Dante/AES67](#problèmes-danteaes67)
+7. [Outils de Diagnostic](#outils-de-diagnostic)
+
+---
+
+## Problèmes Audio
+
+### Pas de son (aucun audio)
+
+#### Symptômes
+- Client parle (bouton PTT activé) mais personne n'entend
+- Pas d'indicateur audio visuel
+
+#### Diagnostic
+
+```bash
+# 1. Vérifier backend audio actif
+sudo journalctl -u pttlive-server | grep "Backend audio"
+# Devrait afficher : "✓ Backend audio : CoreAudio/JACK/PipeWire"
+
+# 2. Vérifier capture audio fonctionne
+# macOS
+system_profiler SPAudioDataType | grep "Default Input"
+
+# Linux avec JACK
+jack_lsp | grep capture
+
+# 3. Vérifier LiveKit connecté
+sudo journalctl -u pttlive-server | grep LiveKit
+# Devrait afficher : "✓ LiveKit connecté"
+```
+
+#### Solutions
+
+**Cause : Microphone non autorisé (navigateur)**
+
+```
+1. Ouvrir les paramètres du navigateur
+2. Site Settings → pttlive.local → Permissions
+3. Microphone : Allow
+4. Rafraîchir la page
+```
+
+**Cause : Backend audio non démarré**
+
+```bash
+# JACK (Linux)
+jackd -d alsa -r 48000 -p 256
+
+# PipeWire (Linux)
+systemctl --user start pipewire pipewire-pulse
+
+# CoreAudio (macOS) : déjà natif, vérifier carte son branchée
+```
+
+**Cause : Routing JACK manquant**
+
+```bash
+# Vérifier connexions
+jack_lsp -c
+
+# Reconnecter manuellement
+jack_connect "system:capture_1" "PTTLive:input_1"
+jack_connect "PTTLive:output_1" "system:playback_1"
+```
+
+---
+
+### Latence élevée (> 200ms)
+
+#### Symptômes
+- Délai perceptible entre parole et réception
+- Conversations difficiles (effet "satellite")
+
+#### Diagnostic
+
+```bash
+# 1. Mesurer latence réseau (ping)
+ping -i 0.2 serveur_ip
+# Devrait être < 10ms en LAN
+
+# 2. Vérifier jitter
+iperf3 -c serveur_ip -u -b 1M
+# Jitter devrait être < 5ms
+
+# 3. Vérifier buffer JACK
+jack_bufsize
+# Typique : 256 samples = 5.3ms @ 48kHz
+
+# 4. Logs PTT Live
+sudo journalctl -u pttlive-server | grep latency
+```
+
+#### Solutions
+
+**Réduire buffer JACK** :
+
+```bash
+# Arrêter JACK
+killall jackd
+
+# Redémarrer avec buffer plus petit
+jackd -d alsa -r 48000 -p 128  # 128 au lieu de 256
+
+# ⚠️ Risque de xruns si CPU faible
+```
+
+**Optimiser jitter buffer PTT Live** :
+
+Éditer `server/config/config.yaml` :
+
+```yaml
+audio:
+  jitterBufferPreset: ULTRA_LOW  # Au lieu de LOW_LATENCY
+```
+
+**Optimiser WiFi** :
+- Forcer 5GHz (pas de 2.4GHz)
+- Réduire nombre de clients par AP (< 15)
+- Vérifier channel WiFi pas surchargé (scanner WiFi)
+
+**Budget latence typique** :
+
+| Composant | Latence |
+|-----------|---------|
+| WiFi | 5-20 ms |
+| WebRTC encode/decode | 20-60 ms |
+| Jitter buffer | 20-40 ms |
+| JACK/backend | 5-10 ms |
+| **Total** | 50-130 ms ✅ |
+
+Si > 200ms, problème réseau probable (WiFi congestionné ou mauvaise couverture).
+
+---
+
+### Coupures audio (audio haché)
+
+#### Symptômes
+- Son qui coupe régulièrement
+- Craquements/pops
+- Audio en "robot"
+
+#### Diagnostic
+
+```bash
+# 1. JACK xruns
+jack_evmon
+# Appuyer Ctrl+C après 30s et noter le nombre de xruns
+# 0 xrun = OK
+# > 5 xruns/min = problème CPU ou buffer trop petit
+
+# 2. CPU usage
+htop
+# CPU > 90% = surchargé
+
+# 3. Packet loss WebRTC
+# Ouvrir navigateur client : chrome://webrtc-internals
+# Chercher "packetsLost" : devrait être < 1%
+
+# 4. Logs backend
+sudo journalctl -u pttlive-server | grep -i "underrun\|overrun"
+```
+
+#### Solutions
+
+**Xruns JACK (CPU overload)** :
+
+```bash
+# Augmenter buffer size
+jackd -d alsa -r 48000 -p 512  # 512 au lieu de 256
+
+# Priorité real-time JACK
+sudo jackd -R -P 70 -d alsa -r 48000 -p 256
+
+# Isoler CPU cores
+# Éditer /etc/default/grub :
+GRUB_CMDLINE_LINUX="isolcpus=2,3"
+# Puis : sudo update-grub && sudo reboot
+```
+
+**Packet loss réseau** :
+
+```bash
+# Vérifier trafic réseau
+iftop -i eth0
+
+# Tester bande passante
+iperf3 -c serveur_ip
+# Devrait être > 100 Mbps en Gigabit
+
+# Vérifier switch (pas de collisions)
+ethtool eth0 | grep -i error
+```
+
+**Codec Opus agressif** :
+
+Réduire le bitrate Opus :
+
+```yaml
+# server/config/config.yaml
+groups:
+  - id: regie
+    opusBitrate: 64000  # 64kbps au lieu de 96kbps
+```
+
+---
+
+### Audio en mono alors que stéréo attendu
+
+#### Cause
+
+Configuration channels à 1 au lieu de 2.
+
+#### Solution
+
+```yaml
+# server/config/config.yaml
+audio:
+  channels: 2  # Stéréo
+```
+
+Redémarrer serveur :
+
+```bash
+sudo systemctl restart pttlive-server
+```
+
+---
+
+## Problèmes Réseau
+
+### Clients ne peuvent pas se connecter
+
+#### Symptômes
+- Erreur "Connection failed" dans le client
+- Timeout lors de la connexion LiveKit
+
+#### Diagnostic
+
+```bash
+# 1. Serveur écoute sur le bon port ?
+sudo netstat -tulpn | grep 7880
+# Devrait afficher : tcp 0.0.0.0:7880 LISTEN
+
+# 2. Firewall bloque ?
+sudo ufw status
+# Ports requis : 7880, 7881, 50000-60000
+
+# 3. Client peut ping serveur ?
+# Sur smartphone/laptop client :
+ping serveur_ip
+
+# 4. Test WebSocket
+# Sur client, ouvrir console navigateur :
+new WebSocket('ws://serveur_ip:7880')
+# Si erreur 404 ou timeout = problème réseau/firewall
+```
+
+#### Solutions
+
+**Ouvrir ports firewall** :
+
+```bash
+sudo ufw allow 7880/tcp
+sudo ufw allow 7881/tcp
+sudo ufw allow 50000:60000/udp
+sudo ufw reload
+```
+
+**Vérifier LiveKit démarre** :
+
+```bash
+sudo journalctl -u pttlive-server | grep -i livekit
+# Chercher "LiveKit server started"
+```
+
+**Tester en local** :
+
+```bash
+# Sur le serveur lui-même
+curl http://localhost:3000/api/health
+# Devrait répondre : {"status":"ok"}
+```
+
+---
+
+### Perte de connexion WiFi fréquente
+
+#### Symptômes
+- Clients se déconnectent toutes les 1-5 minutes
+- Reconnexion automatique ou manuelle requise
+
+#### Diagnostic
+
+```bash
+# Sur l'Access Point (exemple UniFi)
+# SSH vers AP
+ssh ubnt@ap_ip
+
+# Vérifier logs
+tail -f /var/log/messages | grep -i disassoc
+
+# Statistiques WiFi
+iwconfig wlan0
+# Chercher "Signal level" : devrait être > -70 dBm
+```
+
+#### Solutions
+
+**Roaming WiFi agressif** :
+
+Activer Fast Roaming (802.11r/k/v) sur les Access Points.
+
+**Channel congestionné** :
+
+```bash
+# Scanner WiFi
+sudo iwlist wlan0 scan | grep -E "Channel|ESSID|Quality"
+
+# Choisir un channel libre (5GHz : 36, 40, 44, 48, 149, 153, etc.)
+```
+
+**Signal faible** :
+
+- Ajouter un Access Point (couverture)
+- Repositionner AP existant (hauteur, line-of-sight)
+- Vérifier puissance TX AP (pas trop faible)
+
+---
+
+## Problèmes Client (PWA)
+
+### Bouton PTT ne fonctionne pas (mobile)
+
+#### Symptômes
+- Appui sur bouton PTT ne fait rien
+- Pas de vibration/feedback
+
+#### Diagnostic
+
+```javascript
+// Console navigateur mobile (via Remote Debug)
+// Chrome Android : chrome://inspect
+// Safari iOS : Safari Desktop > Develop > iPhone
+
+// Tester événement touch
+document.getElementById('ptt-button').addEventListener('touchstart', (e) => {
+  console.log('Touch start:', e);
+});
+```
+
+#### Solutions
+
+**HTTPS requis** :
+
+Les APIs Web modernes (microphone, vibration) nécessitent HTTPS.
+
+```bash
+# Générer certificat auto-signé
+openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes
+
+# Configurer serveur HTTPS (voir DEPLOYMENT.md)
+```
+
+Accéder via `https://serveur_ip` (accepter certificat dans navigateur).
+
+**Microphone non débloqué (iOS)** :
+
+Sur iOS, l'audio nécessite une interaction utilisateur.
+
+```javascript
+// Ajouter un bouton "Unlock Audio" au premier lancement
+async function unlockAudio() {
+  const audio = new Audio();
+  await audio.play();
+  audio.pause();
+  console.log('Audio unlocked');
+}
+```
+
+---
+
+### PWA ne s'installe pas (iOS)
+
+#### Symptômes
+- Bouton "Add to Home Screen" absent
+- Pas de popup d'installation
+
+#### Cause
+
+Sur iOS, l'installation PWA est **manuelle** (pas de prompt automatique).
+
+#### Solution
+
+Afficher un message d'aide :
+
+```javascript
+// Détecter iOS
+const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent);
+
+if (isIOS) {
+  // Afficher instructions
+  alert(`Pour installer PTT Live :
+1. Appuyez sur le bouton Partage (⬆️)
+2. Sélectionnez "Sur l'écran d'accueil"
+3. Appuyez sur "Ajouter"`);
+}
+```
+
+---
+
+### Notifications Web Push ne fonctionnent pas
+
+#### Diagnostic
+
+```javascript
+// Console navigateur
+if ('Notification' in window) {
+  console.log('Notification permission:', Notification.permission);
+  // granted = OK
+  // denied = utilisateur a refusé
+  // default = pas encore demandé
+}
+
+if ('serviceWorker' in navigator) {
+  navigator.serviceWorker.ready.then(reg => {
+    console.log('Service Worker:', reg);
+  });
+}
+```
+
+#### Solutions
+
+**Permissions non accordées** :
+
+```javascript
+async function requestNotificationPermission() {
+  const permission = await Notification.requestPermission();
+  if (permission === 'granted') {
+    console.log('Notifications autorisées');
+  } else {
+    alert('Veuillez autoriser les notifications dans les paramètres du navigateur');
+  }
+}
+```
+
+**Service Worker non enregistré** :
+
+```bash
+# Vérifier fichier sw.js existe
+ls client/public/sw.js
+
+# Vérifier enregistrement dans main.js
+grep -r "serviceWorker.register" client/src/
+```
+
+---
+
+## Problèmes Serveur
+
+### Serveur ne démarre pas
+
+#### Diagnostic
+
+```bash
+# Logs détaillés
+sudo journalctl -u pttlive-server -n 100 --no-pager
+
+# Vérifier port 3000 pas déjà utilisé
+sudo lsof -i :3000
+# Si occupé, tuer le processus ou changer le port
+
+# Vérifier Node.js version
+node --version  # Devrait être >= 18
+```
+
+#### Solutions
+
+**Port déjà utilisé** :
+
+```bash
+# Tuer processus existant
+sudo kill $(sudo lsof -t -i:3000)
+
+# Ou changer port dans .env
+echo "PORT=3001" >> server/.env
+```
+
+**Dépendances manquantes** :
+
+```bash
+cd server
+npm install
+```
+
+**Permissions audio (Linux)** :
+
+```bash
+# Ajouter utilisateur au groupe audio
+sudo usermod -a -G audio $USER
+
+# Reboot requis
+sudo reboot
+```
+
+---
+
+### Crash serveur après quelques heures (memory leak)
+
+#### Diagnostic
+
+```bash
+# Surveiller RAM
+watch -n 1 free -h
+
+# Logs avant crash
+sudo journalctl -u pttlive-server --since "1 hour ago" | grep -i error
+```
+
+#### Solutions
+
+**Limiter RAM dans systemd** :
+
+Éditer `/etc/systemd/system/pttlive-server.service` :
+
+```ini
+[Service]
+MemoryLimit=4G
+MemoryMax=4G
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart pttlive-server
+```
+
+**Garbage collection Node.js** :
+
+```bash
+# Lancer Node avec options GC
+node --max-old-space-size=2048 --expose-gc index.js
+```
+
+---
+
+## Problèmes JACK/Audio Backend
+
+### JACK ne démarre pas
+
+#### Symptômes
+
+```bash
+jackd -d alsa -r 48000
+# Erreur : "Cannot lock down memory area (Cannot allocate memory)"
+```
+
+#### Diagnostic
+
+```bash
+# Vérifier limites memlock
+ulimit -l
+# Devrait être "unlimited"
+
+# Vérifier utilisateur dans groupe audio
+groups $USER
+# Devrait contenir "audio"
+```
+
+#### Solutions
+
+**Configurer memlock** :
+
+Éditer `/etc/security/limits.conf` :
+
+```
+@audio   -  memlock    unlimited
+@audio   -  rtprio     95
+```
+
+Reboot requis :
+
+```bash
+sudo reboot
+```
+
+---
+
+### JACK démarre mais pas de son
+
+#### Diagnostic
+
+```bash
+# Ports JACK disponibles ?
+jack_lsp
+
+# Devrait afficher :
+# system:capture_1
+# system:playback_1
+# PTTLive:input_1
+# PTTLive:output_1
+
+# Connexions actives ?
+jack_lsp -c
+
+# Devrait afficher des connexions
+```
+
+#### Solution
+
+```bash
+# Connecter manuellement
+jack_connect "system:capture_1" "PTTLive:input_1"
+jack_connect "PTTLive:output_1" "system:playback_1"
+
+# Ou utiliser QjackCtl (GUI)
+qjackctl
+# Cliquer "Graph" et faire les connexions visuellement
+```
+
+---
+
+## Problèmes Dante/AES67
+
+### Dante Virtual Soundcard ne s'affiche pas dans Dante Controller
+
+#### Diagnostic
+
+```bash
+# macOS : DVS est-il démarré ?
+ps aux | grep "Dante Virtual Soundcard"
+
+# Firewall bloque Dante ?
+# Dante utilise :
+# - UDP 319, 320 (PTP)
+# - UDP 4440, 4444, 4455 (Dante Discovery)
+# - UDP 14336-14591 (Audio flows)
+```
+
+#### Solutions
+
+**Désactiver firewall temporairement** :
+
+```bash
+# macOS
+sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off
+
+# Linux
+sudo ufw disable
+```
+
+Si ça fonctionne, ajouter des règles firewall spécifiques :
+
+```bash
+# Linux
+sudo ufw allow 319:320/udp
+sudo ufw allow 4440:4455/udp
+sudo ufw allow 14336:14591/udp
+```
+
+**Vérifier réseau** :
+
+- Même subnet que les équipements Dante (ex: 192.168.1.x/24)
+- Branché sur le même switch
+- IGMP snooping activé sur le switch
+
+---
+
+### Latence Dante trop élevée (> 50ms)
+
+#### Diagnostic
+
+Ouvrir **Dante Controller** :
+
+1. Device View → Sélectionner DVS
+2. Device Config → Dante tab
+3. Vérifier "Latency" : 5ms ou 10ms recommandé
+
+#### Solution
+
+Réduire latency dans DVS :
+
+1. Ouvrir **Dante Virtual Soundcard**
+2. Settings → Latency : 2ms ou 5ms (au lieu de 10ms)
+3. Restart
+
+**Attention** : Latence < 5ms risque de coupures si réseau chargé.
+
+---
+
+### PTP non synchronisé (AES67)
+
+#### Symptômes
+
+```bash
+sudo ptp4l -i eth0 -f /etc/ptp4l.conf -m
+# Offset > 1000 ns (> 1µs)
+```
+
+#### Diagnostic
+
+```bash
+# Switch supporte PTP ?
+# Vérifier config switch (PTP activé)
+
+# PTP master présent sur le réseau ?
+sudo tcpdump -i eth0 -n 'port 319 or port 320'
+# Devrait afficher des paquets PTP Sync/Follow_Up
+```
+
+#### Solutions
+
+**Aucun PTP master** :
+
+Configurer un équipement comme grandmaster (ex: console AES67).
+
+Ou lancer un PTP master software (déconseillé en production) :
+
+```bash
+# Mode master (remplacer slaveOnly par masterOnly dans config)
+sudo ptp4l -i eth0 --masterOnly -m
+```
+
+**Switch ne route pas PTP** :
+
+Vérifier config switch :
+- PTP enabled sur tous les ports
+- Transparent Clock ou Boundary Clock
+
+---
+
+## Outils de Diagnostic
+
+### Logs Serveur
+
+```bash
+# Temps réel
+sudo journalctl -u pttlive-server -f
+
+# Depuis le démarrage
+sudo journalctl -u pttlive-server --since today
+
+# Filtrer erreurs uniquement
+sudo journalctl -u pttlive-server -p err
+```
+
+### Monitoring Réseau
+
+```bash
+# Trafic réseau temps réel
+iftop -i eth0
+
+# Statistiques interface
+ip -s link show eth0
+
+# Connexions actives
+ss -tunap | grep -E '7880|50000'
+```
+
+### Monitoring Audio
+
+```bash
+# JACK
+jack_evmon       # Surveille xruns
+jack_bufsize     # Taille buffer
+jack_samplerate  # Sample rate
+
+# PipeWire
+pw-top           # CPU usage par client
+pw-cli dump      # État complet
+```
+
+### Client (Navigateur)
+
+**Chrome DevTools** :
+
+1. F12 → Console : erreurs JavaScript
+2. Network : vérifier requêtes API (200 OK attendu)
+3. Application → Service Workers : vérifier enregistré
+4. `chrome://webrtc-internals` : stats WebRTC détaillées
+
+**Firefox DevTools** :
+
+1. F12 → Console
+2. `about:webrtc` : stats WebRTC
+
+---
+
+## Checklist Rapide
+
+### Problème : Pas de son
+
+- [ ] Microphone autorisé navigateur ?
+- [ ] Backend audio démarré (JACK/PipeWire) ?
+- [ ] Ports JACK connectés ?
+- [ ] LiveKit connecté (logs serveur) ?
+
+### Problème : Latence élevée
+
+- [ ] Ping < 10ms ?
+- [ ] Buffer JACK = 256 samples ?
+- [ ] WiFi 5GHz ?
+- [ ] Jitter buffer = LOW_LATENCY ?
+
+### Problème : Coupures audio
+
+- [ ] JACK xruns = 0 ?
+- [ ] CPU < 70% ?
+- [ ] Packet loss < 1% ?
+- [ ] Buffer JACK >= 256 ?
+
+### Problème : Connexion impossible
+
+- [ ] Firewall ports ouverts (7880, 50000-60000) ?
+- [ ] LiveKit démarre (journalctl) ?
+- [ ] Client peut ping serveur ?
+- [ ] HTTPS si PWA ?
+
+---
+
+## Support
+
+Si le problème persiste :
+
+1. Collecter logs :
+   ```bash
+   sudo journalctl -u pttlive-server > /tmp/pttlive.log
+   jack_lsp -c > /tmp/jack-connections.txt
+   ```
+
+2. Ouvrir une issue GitHub avec :
+   - Description du problème
+   - Logs serveur
+   - Version OS (client et serveur)
+   - Configuration audio (carte son, backend)
+
+**GitHub Issues** : https://github.com/votre-user/ptt-live/issues
+
+---
+
+**Dernière mise à jour** : 2026-05-26
+**Version** : 0.1.0 (Phase 3)