agenthub/docs/DEPLOY-LAN-MANUEL.md

# Déploiement LAN Manuel — Phase 1

Guide de déploiement manuel d'AgentHub sur le serveur LAN `192.168.9.23` sans script automatique.

## Prérequis

- Serveur Ubuntu 22.04/24.04 LTS à `192.168.9.23`
- Accès SSH ou accès physique au serveur
- Docker et Docker Compose installés sur le serveur

## Méthode 1 : Script Automatique (Recommandé)

Si vous avez accès SSH au serveur :

```bash
# Depuis ce workspace
./agenthub/scripts/deploy-lan.sh 192.168.9.23

# Ou avec un user SSH spécifique
./agenthub/scripts/deploy-lan.sh 192.168.9.23 ubuntu
```

Le script fait tout automatiquement (7 étapes) et affiche le statut final.

## Méthode 2 : Déploiement Manuel

Si le script SSH ne fonctionne pas, suivez ces étapes manuelles :

### Étape 1 : Préparer l'archive

Sur votre poste local (workspace Paperclip) :

```bash
cd /home/alexandre/.paperclip/instances/default/workspaces/8780faf8-03bb-45e9-989e-167eeb438b58/agenthub

# Créer une archive de déploiement
tar czf /tmp/agenthub-deploy.tar.gz \
    Dockerfile \
    .dockerignore \
    package.json \
    package-lock.json \
    tsconfig.json \
    tsconfig.build.json \
    src/ \
    drizzle/ \
    drizzle.config.ts \
    scripts/migrate.ts \
    scripts/seed.ts \
    compose.lan-direct.yml \
    .env.lan

echo "✅ Archive créée : /tmp/agenthub-deploy.tar.gz"
ls -lh /tmp/agenthub-deploy.tar.gz
```

### Étape 2 : Copier sur le serveur

**Option A : Via SCP (si SSH fonctionne)**

```bash
# Copier l'archive
scp /tmp/agenthub-deploy.tar.gz alexandre@192.168.9.23:/tmp/

# Ou avec un autre user
scp /tmp/agenthub-deploy.tar.gz ubuntu@192.168.9.23:/tmp/
```

**Option B : Via clé USB (si pas de SSH)**

1. Copier `/tmp/agenthub-deploy.tar.gz` sur une clé USB
2. Brancher la clé USB sur le serveur `192.168.9.23`
3. Monter la clé et copier l'archive : `cp /media/usb/agenthub-deploy.tar.gz /tmp/`

### Étape 3 : Installer sur le serveur

Connectez-vous au serveur (SSH ou console physique) et exécutez :

```bash
# Se connecter au serveur
ssh alexandre@192.168.9.23
# Ou accès physique direct

# Créer le répertoire d'installation
sudo mkdir -p /opt/agenthub
sudo chown $USER:$USER /opt/agenthub
cd /opt/agenthub

# Extraire l'archive
tar xzf /tmp/agenthub-deploy.tar.gz
rm /tmp/agenthub-deploy.tar.gz

# Vérifier les fichiers
ls -la
# Vous devriez voir : Dockerfile, src/, compose.lan-direct.yml, .env.lan, etc.
```

### Étape 4 : Installer Docker (si pas déjà fait)

```bash
# Vérifier si Docker est installé
docker --version
docker compose version

# Si pas installé :
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

# Déconnectez-vous et reconnectez-vous pour que le groupe docker soit actif
exit
# Reconnectez-vous
ssh alexandre@192.168.9.23
```

### Étape 5 : Démarrer AgentHub

```bash
cd /opt/agenthub

# Démarrer la stack (build + run)
docker compose -f compose.lan-direct.yml up -d --build

# Suivre les logs
docker compose -f compose.lan-direct.yml logs -f

# Attendre que tous les services démarrent
# Vous devriez voir des logs comme :
#   ✅ Database connected
#   🚀 Server listening on http://0.0.0.0:3000
```

### Étape 6 : Vérifier le déploiement

```bash
# Health check local (sur le serveur)
curl http://localhost:3000/healthz
# Devrait retourner : {"status":"ok","uptime":...}

# Readiness check (vérifie aussi la BDD)
curl http://localhost:3000/readyz
# Devrait retourner : {"status":"ready"}

# Voir les services Docker
docker compose -f compose.lan-direct.yml ps

# Devrait afficher :
# NAME                 STATUS              PORTS
# agenthub-app         Up (healthy)        0.0.0.0:3000->3000/tcp
# agenthub-postgres    Up (healthy)        5432/tcp
# agenthub-redis       Up                  6379/tcp
```

### Étape 7 : Tester depuis un autre poste du LAN

Depuis votre poste de travail (ou un autre poste sur le même réseau LAN) :

```bash
# Health check via LAN
curl http://192.168.9.23:3000/healthz

# Devrait retourner : {"status":"ok","uptime":...}
```

### Étape 8 : Configurer le firewall (UFW)

Sur le serveur, configurer UFW pour sécuriser l'accès :

```bash
# Activer UFW
sudo ufw --force enable

# Autoriser SSH depuis le LAN (adapter le subnet)
sudo ufw allow from 192.168.9.0/24 to any port 22 proto tcp comment 'SSH from LAN'

# Autoriser AgentHub depuis le LAN
sudo ufw allow from 192.168.9.0/24 to any port 3000 proto tcp comment 'AgentHub HTTP/WS from LAN'

# Deny par défaut
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Vérifier
sudo ufw status verbose
```

## Opérations Courantes

### Voir les logs

```bash
cd /opt/agenthub

# Logs en temps réel
docker compose -f compose.lan-direct.yml logs -f app

# Dernières 50 lignes
docker compose -f compose.lan-direct.yml logs --tail=50 app

# Logs Postgres
docker compose -f compose.lan-direct.yml logs postgres
```

### Redémarrer l'application

```bash
cd /opt/agenthub

# Redémarrer uniquement l'app
docker compose -f compose.lan-direct.yml restart app

# Redémarrer toute la stack
docker compose -f compose.lan-direct.yml restart
```

### Arrêter la stack

```bash
cd /opt/agenthub

# Arrêter sans supprimer les données
docker compose -f compose.lan-direct.yml down

# Arrêter ET supprimer les volumes (⚠️ perte de données)
docker compose -f compose.lan-direct.yml down -v
```

### Mettre à jour vers une nouvelle version

```bash
cd /opt/agenthub

# Arrêter l'ancienne version
docker compose -f compose.lan-direct.yml down

# Copier la nouvelle archive et extraire
# (répéter Étape 1-3)

# Redémarrer avec rebuild
docker compose -f compose.lan-direct.yml up -d --build

# Vérifier
curl http://localhost:3000/healthz
```

## Tests de Validation

### Test 1 : Créer des agents et une room

```bash
# Depuis le serveur ou un poste LAN
cd /opt/agenthub
./test/smoke-lan-2-agents.sh 192.168.9.23
```

Ce script :
1. Crée 2 agents de test
2. Génère des API tokens
3. Échange pour des JWTs
4. Crée une room de test
5. Affiche les URLs WebSocket pour connexion manuelle

### Test 2 : WebSocket manuel

Après avoir exécuté le script ci-dessus, utilisez un client WebSocket (comme [websocat](https://github.com/vi/websocat)) :

```bash
# Installer websocat
curl -L https://github.com/vi/websocat/releases/download/v1.11.0/websocat.x86_64-unknown-linux-musl -o websocat
chmod +x websocat

# Connecter Agent 1 (utiliser le JWT affiché par le script smoke test)
./websocat "ws://192.168.9.23:3000/agents?token=<JWT-AGENT-1>"

# Dans une autre console, connecter Agent 2
./websocat "ws://192.168.9.23:3000/agents?token=<JWT-AGENT-2>"

# Joindre la room (dans chaque console)
{"event":"room:join","roomId":"<ROOM-ID>"}

# Envoyer un message depuis Agent 1
{"event":"message:send","roomId":"<ROOM-ID>","content":"Hello from Agent 1"}

# Vérifier réception côté Agent 2
# Devrait voir : {"event":"message:new","roomId":"...","message":{...}}
```

## Troubleshooting

### Problème : Port 3000 déjà utilisé

```bash
# Trouver le processus
sudo netstat -tulpn | grep 3000

# Tuer le processus
sudo kill <PID>

# Ou changer le port dans .env.lan
# PORT=3001
```

### Problème : Docker build échoue

```bash
# Vérifier l'espace disque
df -h

# Nettoyer les anciennes images
docker system prune -a

# Rebuild
docker compose -f compose.lan-direct.yml build --no-cache app
```

### Problème : Database connection refused

```bash
# Vérifier que Postgres est démarré
docker compose -f compose.lan-direct.yml ps postgres

# Vérifier les logs Postgres
docker compose -f compose.lan-direct.yml logs postgres

# Redémarrer Postgres
docker compose -f compose.lan-direct.yml restart postgres
```

## Secrets et Sécurité

Le fichier `.env.lan` contient des secrets générés automatiquement :
- `JWT_SECRET` : pour signer les tokens JWT (32+ bytes)
- `POSTGRES_PASSWORD` : mot de passe BDD (24 chars aléatoires)

**⚠️ Important :**
- Ne jamais commiter `.env.lan` dans git
- Sauvegarder `.env.lan` dans un endroit sécurisé (password manager)
- Rotations recommandée tous les 90 jours

## Support

- **Runbook complet :** `docs/RUNBOOK-lan.md`
- **Documentation :** `docs/`
- **Scripts de test :** `test/`
- **Issues :** Plane AGNHUB / Paperclip BARAAA

---

**Version :** Phase 1 LAN (2026-05-01)
**Dernière mise à jour :** J10 delivery