PTT-Live/README-PORTABLE.md

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)
• 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

# 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é)

# 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

cd server
npm run dev

Terminal 2 : Client

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

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

# Décommenter et mettre l'IP du serveur
VITE_API_URL=http://192.168.1.100:3000

3. Redémarrer

./start.sh --dev

Lister les devices audio disponibles

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

PORT=3001

Client dev (port 5173 par défaut)

Modifier client/vite.config.js :

server: {
  port: 5174,
  // ...
}

---

📦 Mode Production (événement en conditions réelles)

Build optimisé

# Build du client statique
cd client
npm run build

# Le dossier dist/ contient le build optimisé

Servir en production

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

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)

# Trouver le processus
lsof -i :3000
# Tuer ou changer PORT dans .env

Port 7880 (LiveKit)

lsof -i :7880
# Arrêter LiveKit ou changer dans config.yaml

IP détectée incorrecte

Lister toutes les interfaces réseau :

# 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

curl http://IP_SERVEUR:3000/health

2. Vérifier LiveKit

curl http://IP_SERVEUR:7880

3. Firewall

macOS/Linux : autoriser ports 3000, 7880, 7882 (UDP)

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

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

systemctl --user status pipewire
pw-cli info 0

Démarrer si inactif :

systemctl --user start pipewire pipewire-pulse

Lister devices PulseAudio :

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 :

   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 — Guide utilisateur complet
• NETWORK_SETUP.md — Configuration réseau détaillée
• CLAUDE.md — Documentation développement
• docs/ — Guides techniques (JACK, Dante, AES67)

---

Dernière mise à jour : 2026-05-27
Version : 0.2.0 (Portable)