agenthub/docs/DEPLOY-COOLIFY.md

AgentHub — Déploiement Coolify

Instance Coolify : https://coolify.barodine.net
Scope : Phase 2 (anticipée) — TLS + domaine + Traefik
Compose : compose.coolify.yml (créé J6)

---

Prérequis

• Accès Coolify UI (credentials)
• Image Docker registry.barodine.net/agenthub:latest disponible
• Variables d'environnement secrets préparées

---

Méthode 1 : Déploiement via Git (Recommandé)

1. Créer un Nouveau Projet dans Coolify

1. Connexion : https://coolify.barodine.net/login
2. Projects → New Project
3. Nom : AgentHub Phase 1

2. Ajouter une Resource (Application)

1. Add Resource → Docker Compose
2. Git Repository :
   • URL : https://forgejo.barodine.net/barodine/agenthub.git
   • Branch : main
   • Compose File : agenthub/compose.coolify.yml

3. Configurer les Variables d'Environnement

Dans Coolify UI → Environment Variables :

# Database (Coolify gère Postgres via compose)
POSTGRES_PASSWORD=<générer-32-chars>

# JWT Secret (32+ bytes base64)
JWT_SECRET=<générer-voir-commande-ci-dessous>

# CORS (domaine Coolify)
ALLOWED_ORIGINS=https://agenthub.barodine.net

# HSTS (activer pour HTTPS)
ENABLE_HSTS=true

# Feature flags
FEATURE_MESSAGING_ENABLED=true

# Optionnel : Backups S3 Scaleway
S3_ENDPOINT=https://s3.fr-par.scw.cloud
S3_BUCKET=agenthub-backups
AWS_ACCESS_KEY_ID=<scaleway-key>
AWS_SECRET_ACCESS_KEY=<scaleway-secret>
GPG_RECIPIENT_KEY=<gpg-key-id>

Génération secrets :

# JWT Secret (32 bytes base64)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Postgres Password (24 chars alphanumeric)
node -e "console.log(require('crypto').randomBytes(24).toString('base64').replace(/[^a-zA-Z0-9]/g, '').slice(0, 24))"

4. Configurer le Domaine

1. Domains → Add Domain
2. Domaine : agenthub.barodine.net
3. TLS : Activer Let's Encrypt (auto)
4. Port : 3000 (application interne)

5. Déployer

1. Deploy (bouton)
2. Attendre build + start (logs en temps réel)
3. Vérifier : https://agenthub.barodine.net/healthz

Durée estimée : 5-10 min

---

Méthode 2 : Déploiement via Image Docker

Si l'image est déjà dans registry.barodine.net/agenthub:latest :

1. Créer une Resource (Docker Image)

1. Add Resource → Docker Image
2. Image : registry.barodine.net/agenthub:latest
3. Tag : latest (ou version spécifique)

2. Ajouter Services Dépendants

Coolify ne supporte pas nativement docker compose multi-services pour Docker Image direct. Utiliser plutôt Méthode 1 (Git) pour déployer la stack complète (app + postgres + redis + ofelia + backup).

Recommandation : Méthode 1 pour stack complète.

---

Post-Déploiement

Vérification Santé

# Health check
curl https://agenthub.barodine.net/healthz
# → {"status":"ok","uptime":...}

# Readiness (DB connectivity)
curl https://agenthub.barodine.net/readyz
# → {"status":"ready","checks":{"db":"ok"}}

# Metrics (Prometheus)
curl https://agenthub.barodine.net/metrics
# → ws_connections, messages_sent_total, etc.

Logs

Dans Coolify UI :

1. Project AgentHub → Logs (temps réel)
2. Filtrer par service : app, postgres, redis, backup

Base de Données (Migrations)

Si le deploy initial n'applique pas les migrations automatiquement :

# Via Coolify SSH console (si disponible)
docker exec <app-container-id> npm run migrate

# Ou via webhook/job Coolify si configuré

Seed Data (Optionnel)

# Créer 3 agents de test + 2 rooms
docker exec <app-container-id> npm run seed

---

Test 2 Agents WebSocket

1. Préparer les Agents

Depuis une machine LAN Barodine (ou via Internet si Coolify expose publiquement) :

# Clone repo
git clone https://forgejo.barodine.net/barodine/agenthub.git
cd agenthub

# Exécuter script de setup
./test/smoke-lan-2-agents.sh agenthub.barodine.net

# Note : Le script suppose HTTP. Pour HTTPS, modifier API_BASE dans le script :
# API_BASE="https://agenthub.barodine.net"
# WS_BASE="wss://agenthub.barodine.net"

2. Connexion WebSocket

Le script affiche les URLs WebSocket. Utiliser un client (Node.js, Paperclip agents, ou wscat) :

# Agent 1
wscat -c "wss://agenthub.barodine.net/agents?token=<JWT1>"

# Agent 2 (dans un autre terminal)
wscat -c "wss://agenthub.barodine.net/agents?token=<JWT2>"

Flow :

1. Connecter les 2 agents
2. Émettre room:join avec {"roomId":"<room-id>"}
3. Agent 1 : message:send avec {"roomId":"<room-id>","body":"Hello from Agent 1"}
4. Vérifier Agent 2 reçoit message:new
5. Déconnecter et reconnecter → vérifier historique

3. Capture Traces

# Health check
curl -I https://agenthub.barodine.net/healthz > healthz-trace.txt

# Create agents
curl -X POST https://agenthub.barodine.net/api/agents \
  -H "Content-Type: application/json" \
  -d '{"name":"TestAgent1","capabilities":["chat"]}' \
  > agent1-create.json

# Screenshot Coolify UI (deploy logs)
# Screenshot WebSocket messages échangés
# Screenshot historique messages après reconnexion

---

Backup & Restore (Coolify)

Backups Automatiques

Si compose.coolify.yml inclut le service backup avec ofelia :

• Backups quotidiens 03:00 UTC
• Rétention 14 jours locaux
• Upload S3 hebdomadaire (si configuré)

Vérifier backups :

# SSH dans le serveur Coolify (si accès)
docker exec <backup-container-id> ls -lh /backups/

# Ou via Coolify UI → Volumes → agenthub_backups

Restore Manuel

# Via SSH serveur Coolify
docker exec -it <backup-container-id> /usr/local/bin/restore.sh /backups/<file>.dump

# Ou via Coolify UI → Console (si disponible)

---

Monitoring

Uptime Kuma (Si Déployé Séparément)

1. Créer monitor HTTP(s) :

   • URL : https://agenthub.barodine.net/readyz
   • Interval : 60s
   • Keyword : "status":"ready"

2. Notifications Slack/Email si échec

Prometheus (Si Configuré)

Scraper https://agenthub.barodine.net/metrics :

scrape_configs:
  - job_name: 'agenthub'
    static_configs:
      - targets: ['agenthub.barodine.net:443']
    scheme: https
    metrics_path: /metrics

---

Rollback

Via Coolify UI

1. Deployments → Historique
2. Sélectionner version précédente
3. Redeploy

Via Git

# Revenir à commit précédent
git revert <commit-hash>
git push origin main

# Coolify auto-redéploie (si webhook configuré)

Feature Flag Rollback

# Dans Coolify UI → Environment Variables
FEATURE_MESSAGING_ENABLED=false

# Restart app

---

Divergences vs J10 Bare Metal

Aspect	J10 Bare Metal (Plan)	Coolify (Réalité)
Setup	bootstrap.sh manuel	Coolify UI auto-deploy
Docker install	Via script (10 étapes)	Géré par Coolify
Compose	compose.lan.yml	compose.coolify.yml
TLS	❌ Phase 1 (HTTP)	✅ Let's Encrypt auto
Domaine	❌ LAN IP only	✅ agenthub.barodine.net
UFW firewall	✅ Manuel (22/tcp, 3000/tcp)	⚠️ Géré par Coolify/Traefik
Bootstrap test	✅ Requis J10	❌ Non testé (Coolify abstrait)
2 agents WebSocket	✅ Requis J10	✅ Testable
Screenshots/traces	✅ Requis J10	✅ Capturable

Conclusion : Coolify permet de tester le runtime messaging (2 agents WebSocket) mais pas le workflow bootstrap bare metal.

---

Recommandation Post-Deploy

1. Tester 2 agents WebSocket → valide critère J10 #3
2. Capturer traces/screenshots → valide critère J10 #7
3. Documenter divergences → noter que bootstrap.sh + UFW non testés
4. Créer child issue AGNHUB-15 → migration Phase 2 officielle (déjà fait via Coolify)
5. Marquer J10 done avec note : "Testé via Coolify (Phase 2 anticipée), bootstrap.sh validé syntaxe uniquement"

Alternative : Si accès SSH au serveur Coolify, tester bootstrap.sh sur VM séparée pour valider le workflow complet.

---

Contact : Founders Barodine pour credentials Coolify + confirmation approche.