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

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

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

```bash
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`:
   ```bash
   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`](./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`](./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

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

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

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

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

```bash
# 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`:
```yaml
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:
   ```bash
   # 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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/`](../docs/)
- **Guide Forgejo**: [`FORGEJO-INSTALL.md`](./FORGEJO-INSTALL.md)
- **Métriques Prometheus**: [`METRICS.md`](./METRICS.md)
- **Dashboard Grafana**: [`grafana-dashboard.json`](./grafana-dashboard.json)
- **Coolify Docs**: https://coolify.io/docs
- **GitHub Webhooks**: https://docs.github.com/en/webhooks
- **Forgejo Docs**: https://forgejo.org/docs