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

```bash
# 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 :**

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

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

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

# Ou via webhook/job Coolify si configuré
```

### Seed Data (Optionnel)

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

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

```bash
# 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

```bash
# 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 :**

```bash
# 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

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

```yaml
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

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

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

### Feature Flag Rollback

```bash
# 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.