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 :

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

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)

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

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

# 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

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

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

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

# 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

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

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

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

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

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

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

# 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

# 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

# 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