Premiere commit - Omika

2026-10-23 18:46:50 +02:00
commit 8ea76c1b24
2155 changed files with 984301 additions and 0 deletions
@@ -0,0 +1,94 @@
+# Déploiement de la pile d'observabilité
+
+## Hébergement recommandé (§21)
+
+```text
+Serveur Windows
+│
+├── Omika API / Worker / services métier
+│
+└── Hyper-V
+     ↓
+   VM Ubuntu Observability
+     ├── OpenTelemetry Collector
+     ├── SigNoz
+     └── ClickHouse
+```
+
+Objectif : isoler **processus / RAM / CPU / disque** de l'observabilité du métier.
+Le métier Omika a **toujours priorité** sur les ressources du serveur.
+
+Si Hyper-V n'est pas disponible : héberger la pile sur une **machine Ubuntu distincte**
+(ou un hôte Docker distinct) ; le principe d'isolation reste identique.
+
+## Ressources initiales proposées (§23, à ajuster)
+
+| Ressource | VM observabilité | Notes |
+|---|---|---|
+| vCPU | 2 (plafond 4) | ne pas allouer tous les cœurs du serveur |
+| RAM | 8 Go (plafond 12 Go) | ClickHouse + SigNoz + Collector |
+| Disque | 100 Go (volume dédié) | ne pas remplir le disque système Windows |
+
+## Ports / firewall (§26, §U)
+
+| Port | Service | Exposition |
+|---|---|---|
+| 4318 | Collector Omika — OTLP HTTP/protobuf | **réseau privé uniquement** (API/Worker Omika) |
+| 4317 | Collector Omika — OTLP gRPC | réseau privé (désactivable) |
+| 3301 | SigNoz UI | accès support autorisé uniquement (VPN/reverse-proxy + auth) |
+| 8085 | SigNoz query-service | interne à la pile |
+| 8123/9000 | ClickHouse | interne à la pile, **jamais** public/mobile |
+
+Règles :
+
+- Le port OTLP n'est **jamais** exposé publiquement.
+- SigNoz est réservé à l'équipe dev/support (§27) ; ClickHouse jamais accessible
+  depuis le mobile/Internet/utilisateurs finaux (§28).
+
+## Installation
+
+1. Créer la VM Ubuntu (ressources ci-dessus).
+2. Installer Docker + Docker Compose.
+3. Copier `infra/observability/` sur la VM.
+4. `cp .env.example .env` puis renseigner les secrets (mot de passe ClickHouse).
+5. Épingler les versions d'images SigNoz aux versions stables officielles.
+6. `docker compose up -d`.
+7. Valider la chaîne (§88) : envoyer un événement test depuis l'API et vérifier
+   qu'il apparaît dans SigNoz (recherche par `EventCode` puis `TraceId`).
+
+## Démarrage / arrêt
+
+```bash
+docker compose up -d      # démarrer
+docker compose down       # arrêter (ne supprime pas les volumes)
+```
+
+Arrêter la pile ne doit avoir **aucun** effet sur Omika (test d'acceptation majeur, §59).
+
+## Stockage / disque (§24)
+
+- Volume dédié pour ClickHouse (`clickhouse-data`), **jamais** le disque système Windows.
+- Taille maximale raisonnable + alerte de remplissage à configurer (ex. 80 %).
+- Le disque d'observabilité ne doit pas pouvoir remplir le disque système d'Omika.
+
+## Rétention (§25, §X)
+
+Proposé pour une première production (à ajuster au volume observé) :
+
+| Signal | Rétention |
+|---|---|
+| Logs | 7 jours |
+| Traces | 7 jours |
+| Métriques | 30 jours |
+
+Ne pas retenir indéfiniment. La rétention se configure côté SigNoz/ClickHouse (TTL).
+
+## Sauvegarde
+
+- Sauvegarder les fichiers de configuration (`otel-collector-config.yaml`, `.env`).
+- Les données ClickHouse sont de la télémétrie : leur perte n'affecte jamais Omika
+  (la sécurité durable reste les JSONL locaux Omika + l'outbox mobile).
+
+## Désinstallation complète
+
+Voir [unplug.md](unplug.md).