# 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).