agenthub/docs/GIT-HOSTING-GUIDE.md

Guide de mise en place Git Hosting pour AgentHub

Guide complet pour choisir et configurer la solution Git (GitHub ou Forgejo) pour héberger le code AgentHub et l'intégrer avec Coolify.

---

Comparaison GitHub vs Forgejo

Critère	GitHub	Forgejo
Hébergement	Cloud (github.com)	Self-hosted (192.168.9.25)
Coût	Gratuit (public) / $4/mois (privé)	Gratuit (infrastructure existante)
Temps d'installation	10 minutes	30-45 minutes
Accessibilité	Internet requis	LAN uniquement (ou exposition via VPN)
Maintenance	Aucune (géré par GitHub)	Mises à jour manuelles
Sécurité données	Hébergé chez Microsoft	100% contrôle local
Webhooks Coolify	✅ Supporté	✅ Supporté
CI/CD natif	GitHub Actions (gratuit limité)	Forgejo Actions (illimité)
Interface web	Moderne, feature-rich	Similaire à GitHub, léger
API REST	Complète et documentée	Compatible Gitea/Forgejo
Collaboration externe	Facile (pull requests publics)	Nécessite accès VPN/réseau
Backup	Automatique (GitHub)	À configurer (Coolify)

---

Recommandation par use case

Choisir GitHub si:

• ✅ Vous voulez un déploiement rapide (10 min)
• ✅ Collaboration avec des contributeurs externes
• ✅ Besoin d'accès depuis n'importe où
• ✅ Pas de contraintes strictes sur l'hébergement des données
• ✅ Utilisation de GitHub Actions pour CI/CD

Choisir Forgejo si:

• ✅ Souveraineté des données (tout reste sur vos serveurs)
• ✅ Projet interne uniquement (pas de collaboration externe)
• ✅ Infrastructure LAN déjà en place
• ✅ Volonté de contrôler 100% de la stack
• ✅ Éviter toute dépendance cloud

---

Installation et configuration GitHub

Prérequis

• Compte GitHub: https://github.com/barodine
• Repository déjà créé: https://github.com/barodine/agenthub
• Personal Access Token (PAT) avec scope repo

Étape 1: Vérifier le repository

Le repository GitHub est déjà créé et le code a été poussé.

Vérification:

git remote -v
# devrait afficher:
# origin  https://github.com/barodine/agenthub.git (fetch)
# origin  https://github.com/barodine/agenthub.git (push)

git branch -a
# devrait afficher:
# * main
# remotes/origin/main

Étape 2: Configurer le webhook Coolify

2.1. Récupérer l'URL du webhook Coolify

1. Aller dans Coolify: https://coolify.barodine.net
2. Créer l'application AgentHub:
   • Projet: Barodine IA
   • Type: Application → Public Repository
   • Git URL: https://github.com/barodine/agenthub
   • Branch: main
   • Build Pack: Dockerfile
3. Une fois créée, aller dans Webhooks → GitHub
4. Copier l'URL du webhook (format: https://coolify.barodine.net/webhooks/xxx)

2.2. Configurer le webhook dans GitHub

1. Ouvrir https://github.com/barodine/agenthub/settings/hooks
2. Cliquer Add webhook
3. Configurer:
   • Payload URL: L'URL copiée de Coolify
   • Content type: application/json
   • Secret: (laisser vide ou copier depuis Coolify)
   • Which events: Just the push event
   • Active: ✅ Coché
4. Cliquer Add webhook

2.3. Tester le webhook

# Faire un commit test
cd /home/alexandre/.paperclip/instances/default/workspaces/8780faf8-03bb-45e9-989e-167eeb438b58/agenthub
echo "# Test webhook" >> README.md
git add README.md
git commit -m "test: Verify GitHub webhook triggers Coolify deploy"
git push origin main

Vérifier dans Coolify que le déploiement démarre automatiquement.

Étape 3: Configuration des secrets GitHub (optionnel)

Pour utiliser GitHub Actions:

1. Aller dans Settings → Secrets and variables → Actions
2. Ajouter les secrets:
   • COOLIFY_WEBHOOK_URL: URL du webhook Coolify
   • POSTGRES_PASSWORD: Mot de passe DB
   • JWT_SECRET: Secret JWT

Étape 4: Configurer les variables d'environnement dans Coolify

Dans l'application AgentHub créée dans Coolify:

NODE_ENV=production
HOST=0.0.0.0
PORT=3000
LOG_LEVEL=info

# PostgreSQL
POSTGRES_HOST=<uuid_db_agenthub>
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<password_from_db_creation>
POSTGRES_DB=postgres

# Sécurité
JWT_SECRET=<générer_32_chars_random>
ALLOWED_ORIGINS=https://agenthub.barodine.net
ENABLE_HSTS=true

# Features
FEATURE_MESSAGING_ENABLED=true

Étape 5: Créer la base de données AgentHub

curl -X POST "https://coolify.barodine.net/api/v1/databases/postgresql" \
  -H "Authorization: Bearer $COOLIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server_uuid": "gw9o6m2ftfvx7g5guf82nkiq",
    "project_uuid": "x9fenmiro11hv1uqij88z88a",
    "environment_name": "production",
    "name": "agenthub-db",
    "description": "PostgreSQL database for AgentHub production",
    "image": "postgres:16-alpine",
    "instant_deploy": true
  }'

Étape 6: Premier déploiement

1. Dans Coolify, cliquer sur Deploy pour l'application AgentHub
2. Attendre la fin du build (~2-5 minutes)
3. Vérifier les logs dans l'onglet Logs
4. Tester l'endpoint /metrics:

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

---

Installation et configuration Forgejo

Étape 1: Installer Forgejo sur 192.168.9.25

Voir le guide complet: FORGEJO-INSTALL.md

Résumé:

1. Créer la base de données Forgejo (déjà fait):

   UUID: rffv6pfwpdftlhunzoishduj
   URL: postgres://postgres:UpW5nyYcNSy88bQiNppIRdFKrtul2Bu4hXzxitzcB4IHU9sAzGc2mkndvKdA1J42@rffv6pfwpdftlhunzoishduj:5432/postgres
   

2. Créer le service Forgejo dans Coolify:

   • Projet: Barodine IA
   • Image: codeberg.org/forgejo/forgejo:9
   • Port: 3000
   • Domain: git.barodine.net
   • Variables d'environnement: voir FORGEJO-INSTALL.md

3. Déployer et configurer:

   • Attendre le démarrage (~2 min)
   • Ouvrir https://git.barodine.net
   • Compléter l'installation initiale

Étape 2: Créer le repository AgentHub dans Forgejo

1. Se connecter à https://git.barodine.net
2. Cliquer sur + → New Repository
3. Configurer:
   • Owner: Votre username
   • Repository Name: agenthub
   • Description: "AgentHub - Hub de communication temps réel pour agents IA"
   • Visibility: Private
   • Initialize Repository: ❌ Non
4. Cliquer Create Repository

Étape 3: Migrer le code de GitHub vers Forgejo

cd /home/alexandre/.paperclip/instances/default/workspaces/8780faf8-03bb-45e9-989e-167eeb438b58/agenthub

# Ajouter Forgejo comme remote (garder GitHub aussi)
git remote add forgejo https://git.barodine.net/username/agenthub.git

# Pousser vers Forgejo
git push forgejo main

# OU: Remplacer GitHub par Forgejo
git remote remove origin
git remote add origin https://git.barodine.net/username/agenthub.git
git push -u origin main

Étape 4: Configurer le webhook Coolify dans Forgejo

1. Dans Forgejo, aller dans le repo agenthub → Settings → Webhooks
2. Cliquer Add Webhook → Forgejo
3. Configurer:
   • Target URL: URL du webhook Coolify (récupérée dans Coolify)
   • HTTP Method: POST
   • POST Content Type: application/json
   • Secret: (copier depuis Coolify si nécessaire)
   • Trigger On: ✅ Push events
   • Active: ✅ Coché
4. Cliquer Add Webhook

Étape 5: Créer l'application AgentHub dans Coolify (source Forgejo)

1. Dans Coolify, créer une nouvelle Application:
   • Projet: Barodine IA
   • Type: Application → Git Repository
   • Source: Private Repository (with Deploy Key)
2. Configurer:
   • Git URL: https://git.barodine.net/username/agenthub.git
   • Branch: main
   • Build Pack: Dockerfile

Important: Générer une Deploy Key SSH:

# Dans Coolify, aller dans l'application → Settings → Deploy Key
# Copier la clé publique SSH générée

# Dans Forgejo, aller dans le repo → Settings → Deploy Keys
# Ajouter la clé publique de Coolify
# ✅ Cocher "Read-only" (pas besoin de write)

Étape 6: Variables d'environnement et déploiement

Même configuration que pour GitHub (voir Étape 4 de la section GitHub).

---

Workflow Git recommandé

Développement local

# 1. Créer une branche de feature
git checkout -b feature/nouvelle-fonctionnalite

# 2. Développer et commiter
git add .
git commit -m "feat: Ajouter nouvelle fonctionnalité"

# 3. Pousser vers le remote
git push origin feature/nouvelle-fonctionnalite

# 4. Créer une Pull Request (GitHub) ou Merge Request (Forgejo)
# Via l'interface web

Déploiement en production

# 1. Merger la PR/MR dans main
# Via l'interface web

# 2. Le webhook déclenche automatiquement le déploiement Coolify

# 3. Vérifier le déploiement
curl https://agenthub.barodine.net/healthz
curl https://agenthub.barodine.net/metrics

Rollback en cas de problème

# Option 1: Via Git (revert)
git revert HEAD
git push origin main
# Le webhook redéploie automatiquement la version précédente

# Option 2: Via Coolify
# Aller dans l'application → Deployments → Cliquer sur un déploiement précédent → "Redeploy"

---

Intégration Prometheus/Grafana

Une fois AgentHub déployé avec l'endpoint /metrics:

Configuration Prometheus

1. Créer/éditer prometheus.yml:

scrape_configs:
  - job_name: 'agenthub'
    scrape_interval: 15s
    static_configs:
      - targets: ['agenthub.barodine.net:443']
    scheme: https

2. Redémarrer Prometheus

Import Dashboard Grafana

1. Ouvrir Grafana
2. Dashboards → Import
3. Uploader agenthub/docs/grafana-dashboard.json
4. Sélectionner la datasource Prometheus
5. Cliquer Import

---

Checklist finale

GitHub Setup

• Repository créé: https://github.com/barodine/agenthub
• Code poussé sur main
• Application créée dans Coolify
• Webhook GitHub → Coolify configuré
• Variables d'environnement configurées
• Base de données PostgreSQL créée
• Premier déploiement réussi
• Endpoint /metrics accessible

Forgejo Setup

• Service Forgejo déployé sur Coolify
• Forgejo accessible via https://git.barodine.net
• Repository agenthub créé dans Forgejo
• Code migré de GitHub vers Forgejo
• Deploy Key SSH configurée (Coolify → Forgejo)
• Webhook Forgejo → Coolify configuré
• Application AgentHub créée dans Coolify (source Forgejo)
• Variables d'environnement configurées
• Base de données PostgreSQL créée
• Premier déploiement réussi
• Endpoint /metrics accessible

Monitoring Setup

• Prometheus configuré pour scraper /metrics
• Dashboard Grafana importé
• Métriques visibles dans Grafana
• Alertes configurées (optionnel)

---

Troubleshooting

Webhook ne déclenche pas le déploiement

1. Vérifier dans GitHub/Forgejo → Settings → Webhooks → Recent Deliveries
2. Vérifier que la réponse HTTP est 200
3. Vérifier les logs Coolify
4. Tester manuellement:

   # Copier l'URL du webhook
   curl -X POST "https://coolify.barodine.net/webhooks/xxx"
   

Build échoue dans Coolify

1. Vérifier les logs de build dans Coolify
2. Problèmes courants:
   • Dockerfile manquant → Vérifier que Dockerfile existe à la racine
   • Dépendances manquantes → Vérifier package.json
   • Variables d'environnement manquantes → Vérifier la config Coolify

Endpoint /metrics retourne 404

1. Vérifier que le serveur démarre:

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

2. Vérifier les logs de l'application dans Coolify
3. Vérifier que le port 3000 est bien mappé
4. Tester en local:

   docker logs <container_id>
   

Forgejo ne démarre pas

1. Vérifier les logs dans Coolify
2. Vérifier la connexion à la base de données:

   docker exec -it forgejo sh
   psql "postgres://postgres:PASSWORD@rffv6pfwpdftlhunzoishduj:5432/postgres"
   

3. Vérifier les variables d'environnement FORGEJO__database__*

---

Prochaines étapes

1. ✅ Choisir entre GitHub ou Forgejo (ou les deux)
2. ✅ Suivre les étapes d'installation correspondantes
3. ✅ Déployer AgentHub via Coolify
4. ⏳ Configurer Prometheus pour scraper /metrics
5. ⏳ Importer le dashboard Grafana
6. ⏳ Tester le monitoring en conditions réelles
7. ⏳ Documenter les procédures opérationnelles (runbook)

---

Ressources

• Documentation AgentHub: /agenthub/docs/
• Guide Forgejo: FORGEJO-INSTALL.md
• Métriques Prometheus: METRICS.md
• Dashboard Grafana: grafana-dashboard.json
• Coolify Docs: https://coolify.io/docs
• GitHub Webhooks: https://docs.github.com/en/webhooks
• Forgejo Docs: https://forgejo.org/docs