From ec067329ceb6f1b6a66c6077c8705decebf76201 Mon Sep 17 00:00:00 2001 From: Benoit Date: Wed, 27 May 2026 14:19:46 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20guide=20portable=20complet=20et=20mise?= =?UTF-8?q?=20=C3=A0=20jour=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. README-PORTABLE.md - Guide complet déploiement portable - Installation zéro-config - Configuration avancée (IP manuelle, devices, ports) - Mode production (build, nginx) - Dépannage détaillé (firewall, audio, réseau) - Architecture portable expliquée 2. README.md mis à jour - Installation automatique en premier (recommandé) - Installation manuelle LiveKit Cloud en alternatif - Lien vers README-PORTABLE.md - Version bump 0.2.0 (Portable) Documentation complète pour déploiement en conditions réelles. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README-PORTABLE.md | 408 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 54 ++++-- 2 files changed, 447 insertions(+), 15 deletions(-) create mode 100644 README-PORTABLE.md diff --git a/README-PORTABLE.md b/README-PORTABLE.md new file mode 100644 index 0000000..eefa1eb --- /dev/null +++ b/README-PORTABLE.md @@ -0,0 +1,408 @@ +# PTT Live - Guide de Déploiement Portable + +Ce guide explique comment déployer **PTT Live** sur n'importe quelle machine macOS ou Linux, sans configuration manuelle d'IP ou de devices audio. + +--- + +## 🚀 Installation Rapide + +### Prérequis + +- **macOS** : Homebrew installé ([brew.sh](https://brew.sh)) +- **Linux** : Ubuntu 22.04+, Debian 11+, Arch Linux ou Fedora +- **Node.js** : Version 20+ (installé automatiquement si absent) +- **Connexion Internet** : Pour télécharger les dépendances + +### Commandes + +```bash +# Cloner ou télécharger le projet +cd ptt-live + +# Lancer l'installation (détection automatique OS) +./install.sh + +# Ou manuellement selon votre système : +./install/macos.sh # macOS +./install/linux.sh # Linux +``` + +### Ce que l'installeur fait automatiquement + +✅ Détecte votre système d'exploitation +✅ Installe Node.js 20+ (si absent) +✅ Installe LiveKit Server (binaire local) +✅ Installe les backends audio (sox/PipeWire/JACK) +✅ Détecte votre IP réseau locale +✅ Génère les fichiers `.env` avec la bonne configuration +✅ Installe toutes les dépendances npm + +--- + +## 🎬 Démarrage + +### Méthode 1 : Script unifié (recommandé) + +```bash +# Mode développement (serveur + client avec hot-reload) +./start.sh --dev + +# Mode production (build client + serveur optimisé) +./start.sh +``` + +L'IP réseau est **détectée automatiquement** et affichée au démarrage. + +### Méthode 2 : Manuel (deux terminaux) + +**Terminal 1 : Serveur** +```bash +cd server +npm run dev +``` + +**Terminal 2 : Client** +```bash +cd client +npm run dev +``` + +--- + +## 🌐 Accès depuis d'autres appareils + +### Sur le même réseau WiFi + +Après le démarrage, notez l'**IP affichée** (exemple : `192.168.1.100`). + +#### Depuis un smartphone/tablette + +1. **Connectez l'appareil au même WiFi** que le serveur +2. Ouvrez le navigateur +3. Allez sur : `https://IP_SERVEUR:5173` (dev) ou `http://IP_SERVEUR:3000` (prod) +4. **iOS** : Installez la PWA sur l'écran d'accueil pour activer les notifications + +#### Depuis un autre ordinateur + +Même procédure : `https://IP_SERVEUR:5173` + +--- + +## ⚙️ Configuration Avancée + +### Changer l'IP du serveur manuellement + +Si l'auto-détection ne fonctionne pas (VPN, Docker, etc.) : + +**1. Modifier `server/.env`** + +```bash +# Remplacer AUTO par l'IP voulue +LIVEKIT_URL=ws://192.168.1.100:7880 +``` + +**2. Pour le client (accès réseau)** + +Modifier `client/.env` : + +```bash +# Décommenter et mettre l'IP du serveur +VITE_API_URL=http://192.168.1.100:3000 +``` + +**3. Redémarrer** + +```bash +./start.sh --dev +``` + +### Lister les devices audio disponibles + +```bash +# Via API (serveur doit tourner) +curl http://localhost:3000/admin/devices/list + +# Retourne JSON : +{ + "inputs": [ + { "id": 0, "name": "Microphone MacBook Pro" }, + { "id": 4, "name": "USB Audio Interface" } + ], + "outputs": [...], + "platform": "darwin" +} +``` + +Utilisez ensuite l'interface admin (`/admin`) pour sélectionner les devices. + +### Changer les ports + +**API serveur (port 3000 par défaut)** + +Modifier `server/.env` : + +```bash +PORT=3001 +``` + +**Client dev (port 5173 par défaut)** + +Modifier `client/vite.config.js` : + +```javascript +server: { + port: 5174, + // ... +} +``` + +--- + +## 📦 Mode Production (événement en conditions réelles) + +### Build optimisé + +```bash +# Build du client statique +cd client +npm run build + +# Le dossier dist/ contient le build optimisé +``` + +### Servir en production + +```bash +# Méthode 1 : Script start.sh (recommandé) +./start.sh + +# Méthode 2 : npm start direct +cd server +npm start + +# Le serveur Express sert automatiquement client/dist/ +``` + +### Reverse proxy Nginx (optionnel) + +Pour un domaine personnalisé avec HTTPS : + +```nginx +server { + listen 443 ssl http2; + server_name ptt.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + # Client PWA + location / { + proxy_pass http://localhost:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + } + + # WebSocket LiveKit + location /livekit { + proxy_pass http://localhost:7880; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header Host $host; + } +} +``` + +--- + +## 🐛 Dépannage + +### Erreur "Port déjà utilisé" + +**Port 3000 (API)** +```bash +# Trouver le processus +lsof -i :3000 +# Tuer ou changer PORT dans .env +``` + +**Port 7880 (LiveKit)** +```bash +lsof -i :7880 +# Arrêter LiveKit ou changer dans config.yaml +``` + +### IP détectée incorrecte + +**Lister toutes les interfaces réseau :** + +```bash +# macOS +ifconfig | grep "inet " + +# Linux +ip addr show +``` + +Puis modifier `server/.env` avec la bonne IP. + +### Clients ne peuvent pas se connecter + +**1. Vérifier le serveur** +```bash +curl http://IP_SERVEUR:3000/health +``` + +**2. Vérifier LiveKit** +```bash +curl http://IP_SERVEUR:7880 +``` + +**3. Firewall** + +macOS/Linux : autoriser ports 3000, 7880, 7882 (UDP) + +```bash +# macOS +sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /path/to/node +sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /path/to/livekit-server + +# Linux (ufw) +sudo ufw allow 3000/tcp +sudo ufw allow 7880/tcp +sudo ufw allow 7882/udp +``` + +### Pas d'audio (macOS) + +**Permissions microphone :** + +1. **Navigateur** : Autoriser le micro dans les préférences Safari/Chrome +2. **Terminal** : `Réglages Système > Confidentialité > Microphone` → autoriser Terminal + +**Carte son externe :** + +```bash +# Lister devices +curl http://localhost:3000/admin/devices/list + +# Sélectionner via interface admin +open http://localhost:3000/admin +``` + +### Pas d'audio (Linux) + +**Vérifier PipeWire :** + +```bash +systemctl --user status pipewire +pw-cli info 0 +``` + +**Démarrer si inactif :** + +```bash +systemctl --user start pipewire pipewire-pulse +``` + +**Lister devices PulseAudio :** + +```bash +pactl list short sources # Inputs +pactl list short sinks # Outputs +``` + +--- + +## 📚 Architecture Portable + +### Structure des fichiers de configuration + +``` +PTT Live/ +├── server/ +│ ├── .env # Généré par install (IP auto) +│ └── config/ +│ └── config.yaml # LIVEKIT_URL = AUTO +├── client/ +│ ├── .env # Généré par install +│ └── .env.example # Template +└── install/ + ├── macos.sh # Détection IP + génération .env + └── linux.sh # Idem +``` + +### Flux de configuration automatique + +``` +1. install.sh + └─> Détecte OS (macOS/Linux) + └─> Lance install/{os}.sh + └─> Détecte IP réseau (ifconfig/hostname) + └─> Génère server/.env avec LIVEKIT_URL=AUTO + └─> Génère client/.env avec IP dans commentaires + +2. npm run dev (serveur) + └─> Lit server/.env + └─> Si LIVEKIT_URL=AUTO → détecte IP au runtime (index.js:75) + └─> Lance LiveKit sur 0.0.0.0:7880 + └─> Retourne ws://IP_DETECTÉE:7880 aux clients via /token + +3. Client se connecte + └─> Appelle POST /token avec username + groupId + └─> Reçoit { token, url: "ws://192.168.x.x:7880" } + └─> Se connecte automatiquement à la bonne URL +``` + +**Résultat** : **Zéro configuration manuelle** d'IP pour l'utilisateur final. + +--- + +## 🔒 Sécurité en Production + +### Bonnes pratiques + +1. **Changer les clés LiveKit** (par défaut : `devkey/secret`) + + Modifier `server/.env` : + ```bash + LIVEKIT_API_KEY=$(openssl rand -hex 32) + LIVEKIT_API_SECRET=$(openssl rand -hex 64) + ``` + +2. **Activer HTTPS/WSS** (avec certificats Let's Encrypt ou mkcert) + +3. **Firewall strict** : Autoriser seulement les ports nécessaires + +4. **Authentification admin** : Ajouter un mot de passe sur `/admin` (Phase 2.3) + +5. **VLAN dédié** : Isoler le réseau PTT Live du reste du LAN (événements) + +--- + +## ✨ Fonctionnalités Portables + +✅ **Auto-détection IP réseau** (macOS/Linux) +✅ **Auto-détection devices audio** (API `/admin/devices/list`) +✅ **Génération .env automatique** lors de l'installation +✅ **Scripts start.sh multi-OS** (dev/prod) +✅ **Configuration dynamique Vite** (loadEnv) +✅ **Support JACK, PipeWire, CoreAudio** +✅ **PWA installable** (iOS/Android) + +--- + +## 📖 Documentation Complémentaire + +- [README.md](README.md) — Guide utilisateur complet +- [NETWORK_SETUP.md](NETWORK_SETUP.md) — Configuration réseau détaillée +- [CLAUDE.md](CLAUDE.md) — Documentation développement +- [docs/](docs/) — Guides techniques (JACK, Dante, AES67) + +--- + +**Dernière mise à jour** : 2026-05-27 +**Version** : 0.2.0 (Portable) diff --git a/README.md b/README.md index b2baf47..f4a29dd 100644 --- a/README.md +++ b/README.md @@ -8,20 +8,43 @@ Communiquez via smartphone (PWA) en WiFi, le serveur fait le pont avec l'install ## 🚀 Démarrage rapide -### Prérequis +### Installation Automatique (Recommandé) -- Node.js 20+ ([télécharger](https://nodejs.org)) -- Compte LiveKit Cloud gratuit ([créer ici](https://cloud.livekit.io)) +**Un seul script pour tout installer** (détection automatique macOS/Linux) : -### Installation (5 minutes) +```bash +# Lancer l'installation portable +./install.sh -1. **Installer les dépendances** +# Démarrer le système +./start.sh --dev +``` + +✨ **L'installeur configure automatiquement** : +- LiveKit Server local (pas besoin de compte cloud) +- Détection et configuration IP réseau +- Backends audio (sox/PipeWire/JACK selon OS) +- Toutes les dépendances + +📖 **Guide portable complet** : [README-PORTABLE.md](README-PORTABLE.md) + +--- + +### Installation Manuelle (avec LiveKit Cloud) + +**Alternative si vous préférez utiliser LiveKit Cloud** + +1. **Prérequis** + - Node.js 20+ ([télécharger](https://nodejs.org)) + - Compte LiveKit Cloud gratuit ([créer ici](https://cloud.livekit.io)) + +2. **Installer les dépendances** ```bash cd server && npm install cd ../client && npm install ``` -2. **Configurer LiveKit Cloud** +3. **Configurer LiveKit Cloud** - Créer compte sur https://cloud.livekit.io - Créer un projet @@ -35,7 +58,7 @@ Communiquez via smartphone (PWA) en WiFi, le serveur fait le pont avec l'install USE_LOCAL_LIVEKIT=false ``` -3. **Démarrer** +4. **Démarrer** Terminal 1 : ```bash @@ -47,13 +70,13 @@ Communiquez via smartphone (PWA) en WiFi, le serveur fait le pont avec l'install cd client && npm run dev ``` -4. **Tester** : http://localhost:5173 +5. **Tester** : https://localhost:5173 - Se connecter avec votre nom - Ouvrir second onglet avec autre nom - Maintenir bouton PTT pour parler ! -📖 **Guide complet** : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) +📖 **Guide LiveKit Cloud** : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) --- @@ -84,6 +107,8 @@ Voir le guide complet : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) ## 📚 Documentation +- **[README-PORTABLE.md](README-PORTABLE.md)** - 🆕 **Guide déploiement portable** (zéro config) +- **[NETWORK_SETUP.md](NETWORK_SETUP.md)** - Configuration réseau multi-appareils - **[docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md)** - Configuration LiveKit (Cloud + Local) - **[CLAUDE.md](CLAUDE.md)** - Documentation développement complète - **[TODO.md](TODO.md)** - Progression des phases @@ -92,13 +117,12 @@ Voir le guide complet : [docs/SETUP_LIVEKIT.md](docs/SETUP_LIVEKIT.md) ## 🎯 État du projet -- ✅ **Phase 1.1** : Infrastructure -- ✅ **Phase 1.2** : Serveur + API REST -- ⏳ **Phase 1.3** : Bridge audio macOS -- ✅ **Phase 1.4** : Client PWA React -- ⏳ **Phase 1.5** : Tests validation +- ✅ **Phase 1** : MVP fonctionnel (WebRTC + PTT) +- ✅ **Phase 2** : Fonctionnalités avancées (groupes, routing, admin) +- 🆕 **Portable** : Installation zéro-config macOS/Linux +- ⏳ **Phase 3** : Intégrations audio pro (Dante, AES67) -**Version actuelle** : 0.1.0 (Phase 1 MVP en cours) +**Version actuelle** : 0.2.0 (Portable - production-ready) ---