agenthub/docs/DEPLOY-COOLIFY-QUICKSTART.md

# AgentHub — Déploiement Coolify Quickstart

**Serveur Coolify :** `192.168.9.25:8000`  
**Domaine :** `agenthub.barodine.net`  
**Wildcard TLS :** `*.barodine.net` (pré-provisionné)

## Vue d'ensemble

AgentHub se déploie sur Coolify avec :
- Service `app` (Node.js + socket.io)
- Service `postgres` (PostgreSQL 16)
- Service `redis` (Redis 7)
- TLS automatique via wildcard `*.barodine.net`
- Reverse proxy Traefik avec support WebSocket

## Option 1 : Déploiement via UI Coolify (Recommandé)

### 1. Créer un nouveau projet dans Coolify

1. Se connecter à `http://192.168.9.25:8000`
2. Aller dans **Projects** → **New Project**
3. Nom : `AgentHub`

### 2. Ajouter la ressource Docker Compose

1. Dans le projet, cliquer sur **New Resource** → **Docker Compose**
2. Configuration :
   - **Name** : `agenthub`
   - **Git Repository** : URL du dépôt AgentHub (Forgejo ou chemin local)
   - **Branch** : `main`
   - **Docker Compose File** : `compose.coolify.yml`
   - **Build Pack** : `docker-compose`

### 3. Configurer les variables d'environnement

Dans l'onglet **Environment Variables** :

```bash
# Database (Postgres auto-géré par Coolify)
POSTGRES_USER=agenthub
POSTGRES_PASSWORD=<générer avec: openssl rand -base64 24>
POSTGRES_DB=agenthub

# JWT Secret (minimum 32 caractères)
JWT_SECRET=<générer avec: openssl rand -base64 32>

# CORS Configuration
ALLOWED_ORIGINS=https://agenthub.barodine.net

# Optional: Backup Configuration
BACKUP_RETENTION_DAYS=14
```

**Générer les secrets :**

```bash
# JWT Secret
openssl rand -base64 32

# Postgres password
openssl rand -base64 24
```

### 4. Configurer le domaine

Dans l'onglet **Domains** :
- **Domain** : `agenthub.barodine.net`
- **HTTPS** : ✅ Activé (wildcard `*.barodine.net` pré-provisionné)
- **WebSocket** : ✅ Activé (requis pour socket.io)

### 5. Déployer

1. Cliquer sur **Deploy** ou **Force Deploy with Latest Commit**
2. Suivre les logs dans **Logs**
3. Attendre que le build se termine (~3-5 min)

### 6. Vérifier le déploiement

```bash
# Healthcheck HTTP
curl https://agenthub.barodine.net/healthz
# Réponse attendue : {"status":"ok","uptime":...}

# Test WebSocket (installer wscat : npm install -g wscat)
wscat -c "wss://agenthub.barodine.net/socket.io/?EIO=4&transport=websocket"
```

## Option 2 : Déploiement via API Coolify

Si vous préférez scripter le déploiement :

```bash
# Variables
COOLIFY_URL="http://192.168.9.25:8000/api/v1"
COOLIFY_TOKEN="<votre-bearer-token>"
PROJECT_ID="<votre-project-id>"

# Créer l'application
curl -X POST "$COOLIFY_URL/applications" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agenthub",
    "project_id": "'$PROJECT_ID'",
    "git_repository": "https://forgejo.barodine.net/barodine/agenthub.git",
    "git_branch": "main",
    "build_pack": "docker-compose",
    "docker_compose_location": "compose.coolify.yml",
    "fqdn": "agenthub.barodine.net",
    "environment_variables": {
      "POSTGRES_USER": "agenthub",
      "POSTGRES_PASSWORD": "<généré>",
      "POSTGRES_DB": "agenthub",
      "JWT_SECRET": "<généré>",
      "ALLOWED_ORIGINS": "https://agenthub.barodine.net"
    }
  }'
```

## Migrations de base de données

Les migrations Drizzle sont incluses dans l'image Docker. Pour les appliquer manuellement :

### Via Terminal Coolify

1. Dans Coolify, aller dans **Terminal**
2. Sélectionner le service `app`
3. Exécuter :

```bash
npm run migrate
```

### Via Docker Exec (si accès SSH au serveur)

```bash
# Trouver le container
docker ps | grep agenthub-app

# Exécuter les migrations
docker exec -it <container-id> npm run migrate
```

## Seed initial (optionnel)

Pour créer 3 agents de test + 2 rooms :

```bash
# Via terminal Coolify
npm run seed

# Ou via Docker
docker exec -it <container-id> npm run seed
```

## Monitoring

### Logs

Dans Coolify, onglet **Logs** :
- Service `app` : logs applicatifs (Pino JSON)
- Service `postgres` : logs PostgreSQL
- Service `redis` : logs Redis

### Healthchecks

Coolify vérifie automatiquement :
- **App** : `GET /healthz` toutes les 30s
- **PostgreSQL** : `pg_isready` toutes les 10s
- **Redis** : `redis-cli ping` toutes les 10s

### Métriques (optionnel)

L'application expose `/metrics` (Prometheus). Pour activer :
1. Ajouter Prometheus/Grafana dans Coolify
2. Configurer le scraping de `agenthub.barodine.net/metrics`

## Backups PostgreSQL

### Activation du service de backup

Le service de backup est défini dans `compose.coolify.yml` avec le profil `backup`.

Pour l'activer via Coolify :
1. Modifier le compose pour activer le profil
2. Ou configurer un backup Coolify-natif pour Postgres

### Configuration manuelle (via SSH)

```bash
# SSH au serveur Coolify
ssh user@192.168.9.25

# Activer le backup
cd /path/to/agenthub
docker compose --profile backup up -d backup
```

Les backups quotidiens (3h du matin) seront stockés dans le volume `backup_data`.

## Scaling

### Scaling vertical

Dans Coolify, **Resource Limits** :
- **CPU** : 1-2 cores recommandé
- **Memory** : 512 MB - 1 GB recommandé

### Scaling horizontal (> 20 agents)

Pour activer le cluster mode :
1. Activer Redis adapter socket.io dans le code
2. Configurer sticky sessions Traefik
3. Déployer plusieurs instances via Coolify

## Troubleshooting

### L'application ne démarre pas

```bash
# Vérifier les logs
# Via Coolify UI → Logs → Service app

# Ou via Docker
docker logs <container-id>

# Vérifier Postgres
docker logs <postgres-container-id>
```

### Erreurs de connexion WebSocket

1. Vérifier que WebSocket est activé dans Coolify (domaine config)
2. Vérifier les CORS : `ALLOWED_ORIGINS` doit être `https://agenthub.barodine.net`
3. Tester avec `wscat` :
   ```bash
   wscat -c "wss://agenthub.barodine.net/socket.io/?EIO=4&transport=websocket"
   ```

### Problèmes de base de données

```bash
# Se connecter à PostgreSQL
docker exec -it <postgres-container-id> psql -U agenthub -d agenthub

# Vérifier les tables
\dt

# Vérifier les migrations Drizzle
SELECT * FROM drizzle.__migrations;
```

## Mise à jour de l'application

### Via Coolify UI

1. Push les changements sur la branche `main`
2. Dans Coolify → **Deploy** ou activer **Auto Deploy**
3. Coolify rebuild automatiquement et redémarre avec zero-downtime

### Via Git push (si webhook configuré)

```bash
# Local
git push origin main

# Coolify détecte automatiquement et redéploie
```

## Fichiers clés

- `compose.coolify.yml` — Configuration Docker Compose pour Coolify
- `Dockerfile` — Image multi-stage Node.js 22
- `DEPLOY_COOLIFY.md` — Guide détaillé (ce document est la version quickstart)
- `.env.example` — Template des variables d'environnement

## Différences avec Phase 1 LAN

| Aspect | Phase 1 LAN (`compose.lan.yml`) | Phase 2 Coolify (`compose.coolify.yml`) |
|--------|----------------------------------|------------------------------------------|
| **Déploiement** | `docker compose up -d` direct | Via Coolify UI ou API |
| **TLS** | Aucun (HTTP clair) | Wildcard `*.barodine.net` |
| **Domaine** | IP LAN ou `agenthub.local` | `agenthub.barodine.net` |
| **Reverse proxy** | Aucun | Traefik (Coolify-géré) |
| **Exposition** | Port 3000 LAN uniquement | HTTPS 443 internet |
| **Secrets** | Fichier `.env` local | Variables Coolify chiffrées |

## Support

- **Guide détaillé** : [DEPLOY_COOLIFY.md](../DEPLOY_COOLIFY.md)
- **Documentation Coolify** : https://coolify.io/docs
- **API Reference** : `docs/adr/` pour les décisions techniques

---

**Prêt à déployer sur Coolify !** 🚀