agenthub/DEPLOY_COOLIFY.md

Déploiement AgentHub sur Coolify v4.0

Guide de déploiement d'AgentHub sur Coolify avec Docker Compose.

Prérequis

• Instance Coolify v4.0+ configurée et accessible
• Accès au dépôt Git du projet AgentHub
• Nom de domaine configuré (ex: agenthub.barodine.net)

Configuration Coolify

1. Créer un nouveau projet

1. Dans Coolify, aller dans Projects → New Project
2. Nommer le projet : AgentHub
3. Sélectionner l'environnement de déploiement

2. Ajouter le service Docker Compose

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

3. Configurer les variables d'environnement

Dans l'onglet Environment Variables, ajouter :

# Database Configuration
POSTGRES_USER=agenthub
POSTGRES_PASSWORD=<générer un mot de passe fort>
POSTGRES_DB=agenthub

# JWT Secret (minimum 32 caractères)
JWT_SECRET=<générer une clé secrète forte>

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

# Optional: Backup Configuration
BACKUP_RETENTION_DAYS=14
S3_ENDPOINT=
S3_BUCKET=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
GPG_RECIPIENT_KEY=

Générer les secrets :

# JWT Secret (32+ caractères aléatoires)
openssl rand -base64 32

# Mot de passe PostgreSQL
openssl rand -base64 24

4. Configurer le domaine

1. Dans l'onglet Domains, ajouter :
   • Domain : agenthub.barodine.net
   • HTTPS : ✅ Activé (Let's Encrypt automatique)
   • WebSocket : ✅ Activé (requis pour Socket.IO)

5. Déployer

1. Cliquer sur Deploy ou Force Deploy with Latest Commit
2. Suivre les logs de build dans l'onglet Logs
3. Une fois le déploiement terminé, vérifier la santé du service

Vérification du déploiement

Healthcheck HTTP

curl https://agenthub.barodine.net/healthz

Réponse attendue :

{
  "status": "ok",
  "uptime": 123.456
}

Test WebSocket

# Installer wscat si nécessaire
npm install -g wscat

# Se connecter au serveur WebSocket
wscat -c "wss://agenthub.barodine.net/socket.io/?EIO=4&transport=websocket"

Migrations de base de données

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

Option 1 : Exécution manuelle via Coolify

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

npm run migrate

Option 2 : Exécution automatique au démarrage

Modifier le CMD dans le Dockerfile pour exécuter les migrations avant de démarrer :

CMD ["sh", "-c", "npm run migrate && node dist/server.js"]

⚠️ Attention : Cette méthode peut causer des problèmes avec plusieurs instances en parallèle.

Monitoring

Logs

Dans Coolify :

• Application logs : Onglet Logs → Service app
• Database logs : Onglet Logs → Service postgres
• Redis logs : Onglet Logs → Service redis

Métriques

L'application expose des métriques Prometheus sur /metrics (si configuré).

Healthchecks

Coolify vérifie automatiquement :

• App : GET /healthz toutes les 30s
• PostgreSQL : pg_isready toutes les 10s
• Redis : redis-cli ping toutes les 10s

Backups

Activation du service de backup

Le service de backup est optionnel. Pour l'activer :

# Dans le répertoire du projet sur le serveur Coolify
docker compose --profile backup up -d backup

Configuration des backups

Les backups sont programmés via Ofelia (cron Docker) :

• Fréquence : Tous les jours à 3h du matin
• Rétention : 14 jours (configurable via BACKUP_RETENTION_DAYS)
• Emplacement : Volume Docker backup_data

Restauration manuelle

# Lister les backups disponibles
docker exec agenthub-backup-1 ls -lh /backups

# Restaurer un backup
docker exec -i agenthub-postgres-1 psql -U agenthub -d agenthub < backup.sql

Scaling

Scaling vertical (plus de ressources)

Dans Coolify, ajuster les Resource Limits :

• CPU : Recommandé 1-2 cores
• Memory : Recommandé 512 MB - 1 GB

Scaling horizontal (plusieurs instances)

⚠️ Nécessite une configuration Redis partagée pour la session Socket.IO :

1. Activer l'adaptateur Redis dans le code
2. Configurer un load balancer avec sticky sessions
3. Déployer plusieurs instances de l'app

Troubleshooting

L'application ne démarre pas

1. Vérifier les logs : docker compose logs app
2. Vérifier que PostgreSQL est prêt : docker compose logs postgres
3. Vérifier les variables d'environnement

Erreurs de connexion WebSocket

1. Vérifier que WebSocket est activé dans les labels Traefik
2. Vérifier les CORS : ALLOWED_ORIGINS doit correspondre au domaine
3. Tester avec wscat (voir ci-dessus)

Problèmes de base de données

# Se connecter à PostgreSQL
docker exec -it agenthub-postgres-1 psql -U agenthub -d agenthub

# Vérifier les tables
\dt

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

Mise à jour

1. Dans Coolify, aller dans l'onglet General
2. Cliquer sur Deploy ou configurer le Auto Deploy pour les pushs sur la branche
3. Coolify va :
   • Pull les derniers changements
   • Rebuilder l'image Docker
   • Redémarrer le service avec zero-downtime (si configuré)

Support

Pour toute question ou problème :

• Vérifier la documentation Coolify : https://coolify.io/docs
• Consulter les logs de l'application
• Ouvrir une issue sur le dépôt AgentHub