---
title: Services annexes
slug: oip-next/v4/services-annexes
icon: {"lucideIcon":"📘"}
createdAt: 2026-08-18T09:20:00.000Z
---

# Vue d'ensemble

Un OAV n'est jamais exécuté seul : il s'appuie sur des services annexes, démarrés localement par Docker Compose en développement, et déployés aux côtés de l'OAV en production.

| Service        | Rôle                                                                  |
| -------------- | --------------------------------------------------------------------- |
| OIP Headless   | Persistance, historisation, ordonnancement des tâches et règles RGPD. |
| Fasst Sessions | Émission et validation des jetons de décrochage.                      |
| PostgreSQL     | Données d'OIP Headless et magasin des sessions de l'OAV.              |
| RabbitMQ       | Acheminement des évènements entre OIP Headless et l'OAV.              |

```mermaid
flowchart LR
    Client[App React] -->|GraphQL| Server[App Express]
    Server -->|REST| Headless[OIP Headless]
    Server -->|HTTP| Sessions[Fasst Sessions]
    Headless --> DB[(PostgreSQL)]
    Server --> DB
    Headless <-->|AMQP| MQ[RabbitMQ]
    Server <-->|AMQP| MQ
```

# OIP Headless

OIP Headless est le service de persistance de l'OIP. Il expose une API REST consommée par le serveur Express de l'OAV, authentifiée par clé d'API.

Il assure :

- la persistance des entités et du `Process` ;
- l'historisation de toutes les écritures et leur annulation par transaction ;
- la programmation des tâches et des *workflows* de tâches ;
- l'application des règles RGPD de chiffrement au repos et de purge automatique ;
- la publication d'évènements vers l'OAV.

Il nécessite une instance PostgreSQL et une instance RabbitMQ.

## Configuration

| Variable                 | Statut      | Description                                                                       |
| ------------------------ | ----------- | --------------------------------------------------------------------------------- |
| `DATABASE_URL`           | Obligatoire | URL PostgreSQL, au format `ecto://[USER]:[PASS]@[HOST]:[PORT]/[DATABASE]`.        |
| `AMQP_URL`               | Obligatoire | URL RabbitMQ, au format `amqp://[USER]:[PASS]@[HOST]:[PORT]/[VHOST]`.             |
| `SECRET_KEY_BASE`        | Obligatoire | Clé de chiffrement et de signature des cookies.                                   |
| `CIPHER_SECRET_KEY_BASE` | Obligatoire | Clé de chiffrement des données, de 256 bits encodée en base64.                    |
| `PHX_HOST`               | Obligatoire | URL du tableau de bord du service.                                                |
| `ECTO_SSL_CERT_PATH`     | Optionnelle | Chemin du certificat racine, requis pour activer SSL sur la connexion PostgreSQL. |
| `LOGGER_LEVEL`           | Optionnelle | Niveau de journalisation du service.                                              |

Côté OAV, le dialogue avec ce service est configuré par les variables `OIP_API_URL`, `OIP_API_KEY` et `OAV_ID`.

:::BlockQuote
**\[info]** Ces variables configurent le service OIP Headless, et non l'OAV. Elles sont renseignées dans le fichier `docker-compose.yml` en développement, ou par l'orchestrateur en production.
:::

# Fasst Sessions

Fasst Sessions résout le contexte client à l'entrée du parcours : il émet des jetons de décrochage et les valide.

Le serveur Express lui transmet le jeton reçu en paramètre d'URL, et reçoit en retour le contexte client résolu, qui est ensuite passé à `resolveProjectFromContext`.

| Élément                            | Valeur                      |
| ---------------------------------- | --------------------------- |
| Port par défaut en développement   | `3005`                      |
| Route d'émission d'un jeton        | `POST /api/sessions/tokens` |
| Variable de configuration côté OAV | `SESSION_SERVICE_URL`       |

Émission d'un jeton en développement :

```shell
curl --request POST \
  --url http://localhost:3005/api/sessions/tokens \
  --header 'Content-Type: application/json' \
  --data '{"applicant":"magic","metadata":{"externalId":"project-AAA"}}'
```

Le service dispose de sa propre base de données.

:::BlockQuote
**\[info]** Ce service est remplaçable. La fonction de rappel `session.resolveContext` permet de résoudre le contexte client auprès d'un service tiers, ou selon une logique métier spécifique.
:::

# PostgreSQL

PostgreSQL héberge deux jeux de données distincts :

| Base                       | Contenu                                               | Variable                                |
| -------------------------- | ----------------------------------------------------- | --------------------------------------- |
| Base d'OIP Headless        | Entités, historique des écritures, `Process`, tâches. | `DATABASE_URL` du service OIP Headless. |
| Base des sessions de l'OAV | Sessions de navigation HTTP.                          | `SESSION_STORE_URL` de l'OAV.           |

Les migrations du modèle de données de l'OAV sont appliquées sur la base d'OIP Headless, par le script `scripts/run-migrations.sh` appelé par la commande `migrate:dev` en développement, et exécuté au démarrage du conteneur en production.

# RabbitMQ

RabbitMQ achemine les évènements entre OIP Headless et l'OAV, et permet de servir plusieurs instances de l'OAV.

| File                | Sens               | Contenu                              |
| ------------------- | ------------------ | ------------------------------------ |
| `<OAV_ID>.events`   | OIP Headless → OAV | Déclenchement des tâches à échéance. |
| `<OAV_ID>.entities` | OIP Headless → OAV | Instantanés de trame projet.         |
| `oip.api.events`    | OAV → OIP Headless | Remontée des statuts de tâches.      |

Côté OAV, la connexion est configurée par les variables `RABBIT_MQ_HOST`, `RABBIT_MQ_USER`, `RABBIT_MQ_PASSWORD` et `RABBIT_MQ_VHOST`.

:::BlockQuote
**\[warn]** L'écoute de la file `<OAV_ID>.events` n'est pas automatique : le consommateur doit être enregistré explicitement (par exemple dans `server/index.mjs`). Sans cet enregistrement, les tâches sont programmées mais jamais exécutées.
:::

# Exploitation en développement

| Commande                 | Effet                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| `docker compose up -d`   | Démarre l'ensemble des services annexes.                           |
| `docker compose ps`      | Liste les services et leur état.                                   |
| `docker compose logs -f` | Suit les journaux de tous les services.                            |
| `docker compose stop`    | Arrête les services en conservant les données.                     |
| `docker compose down -v` | Arrête les services **et supprime les volumes**, donc les données. |

:::BlockQuote
**\[warn]** `docker compose down -v` est destructif et réservé au poste de développement.
:::

# Déploiement

Un OAV en production mobilise cinq services :

1. l'OAV lui-même, distribué sous forme d'image Docker ;
2. le service de sessions et sa base de données ;
3. OIP Headless ;
4. PostgreSQL, hébergeant les données d'OIP Headless et les sessions de l'OAV ;
5. RabbitMQ.

# Résumé

- Quatre services annexes entourent l'OAV : OIP Headless, Fasst Sessions, PostgreSQL et RabbitMQ ;
- OIP Headless porte les données, l'historisation, l'ordonnancement des tâches et les règles RGPD ;
- Fasst Sessions n'intervient qu'au décrochage, et peut être remplacé par un service tiers ;
- trois files RabbitMQ structurent les échanges asynchrones.
