# Procédure de Mise à Jour de Bifrost (Gateway LLM)

## Contexte et Emplacement
- **Emplacement** : `/volume1/docker/bifrost/`
- **Compose** : `/volume1/docker/bifrost/docker-compose.yml`
- **Port** : `3085` (interne n8n, non exposé WAN direct)
- **Réseau** : `n8n`

---

## Précautions Critiques et Pièges Connus

1. **Pin Explicite de Version Obligatoire** :
   Ne jamais laisser `image: maximhq/bifrost` sans tag (ce qui équivaut à un `:latest` implicite et provoque des dérives silencieuses). Toujours épingler la version cible exacte, ex. : `image: maximhq/bifrost:v1.6.11`.

2. **Sauvegarde Double Préalable** :
   Dans `/volume1/docker/bifrost/data/`, il existe deux fichiers de configuration essentiels :
   - `config.db` (base SQLite contenant la gouvernance, les virtual keys, les budgets et le mapping providers)
   - `config.json` (configuration des providers et clés API amont)
   Toujours sauvegarder les deux fichiers avec horodatage avant toute intervention :
   ```bash
   cd /volume1/docker/bifrost/data
   cp config.db "config.db.bak-$(date +%Y%m%d-%H%M%S)"
   cp config.json "config.json.bak-$(date +%Y%m%d-%H%M%S)"
   ```

3. **Mécanisme de Rechargement des Clés Provider (Governance)** :
   Au redémarrage d'un conteneur recréé, les virtual keys utilisent les autorisations enregistrées dans la table `governance_virtual_key_provider_configs` (`allow_all_keys = 1`).
   Si après un restart un appel renvoie `provider not found`, vérifier et réactiver `allow_all_keys` dans `config.db` :
   ```sql
   UPDATE governance_virtual_key_provider_configs SET allow_all_keys = 1;
   ```

4. **Taille de `logs.db`** :
   Le fichier `/volume1/docker/bifrost/data/logs.db` enregistre l'historique complet des requêtes et tokens. Il peut atteindre plusieurs dizaines de Go (~98 Go relevés en août 2026). Ne pas tronquer sans validation explicite.

---

## Procédure Standard de Mise à Jour

```bash
# 1. Sauvegardes
cd /volume1/docker/bifrost/data
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
cp config.db "config.db.bak-$TIMESTAMP"
cp config.json "config.json.bak-$TIMESTAMP"

# 2. Modifier le tag dans docker-compose.yml
# image: maximhq/bifrost:vX.Y.Z

# 3. Pull et Recréation
cd /volume1/docker/bifrost
docker compose pull
docker compose up -d --force-recreate

# 4. Vérifications
curl -s http://192.168.100.33:3085/health        # doit renvoyer {"components":{"db_pings":"ok"},"status":"ok"}
curl -s http://192.168.100.33:3085/api/version   # doit renvoyer la nouvelle version

# 5. Test réel de complétion avec une Virtual Key valide
curl -s http://192.168.100.33:3085/v1/chat/completions   -H "Authorization: Bearer $BIFROST_VK"   -H "Content-Type: application/json"   -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 5
  }'
```