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 :

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

# 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

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

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

npm run migrate

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

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

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

# 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

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

   wscat -c "wss://agenthub.barodine.net/socket.io/?EIO=4&transport=websocket"
   

Problèmes de base de données

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

# 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
• Documentation Coolify : https://coolify.io/docs
• API Reference : docs/adr/ pour les décisions techniques

---

Prêt à déployer sur Coolify ! 🚀