Lancement du projet

16 min

Vue d'ensemble

Un OAV en cours de développement mobilise trois éléments qui se démarrent séparément :

les services annexes, orchestrés par Docker Compose ;

l'application Express, qui porte la logique et l'accès aux données ;

l'application React, servie par Vite.

Cette page décrit leur mise en route, dans l'ordre, puis le décrochage sur le parcours.

flowchart LR
    A[docker compose up -d] --> B[Implementation of the handoff]
    B --> C[npm run start-server:dev]
    C --> D[npm run front:dev]
    D --> E[Handoff on the OAV]

[info] Cette page suppose un projet déjà initialisé.

Démarrage des services annexes

docker compose up -d

Cette commande démarre l'ensemble des services nécessaires à l'exécution de l'OAV :

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	Base de données d'OIP Headless et magasin des sessions de l'OAV.
RabbitMQ	Acheminement des évènements entre OIP Headless et l'OAV.

Vérifiez que les conteneurs sont démarrés :

docker compose ps

[info] Le détail de ces services et de leur configuration est décrit dans la section « Services annexes ».

Implémentation du décrochage

[warn] Avant de pouvoir lancer la partie serveur, il est nécessaire de modifier le fichier server/index.mjs pour fournir une implémentation aux fonctions resolveProjectFromContext, resolveFirstView et validateProjectId. Un exemple d'implémentation de chacune de ces fonctions est fourni dans le fichier.

Fonction	Rôle	Valeur de retour
resolveProjectFromContext	Résout le projet associé au contexte client, et le crée s'il n'existe pas.	Identifiant de l'entité Project.
validateProjectId	Valide un projectId passé en paramètre d'URL.	Booléen.
resolveFirstView	Détermine la vue d'entrée du parcours.	Identifiant de vue.

Exemple d'implémentation — server/index.mjs

import { logger } from '@fasstech/logger';
import { getEnv, handleTask, start as startServer } from '@fasstech/oip-starter-utils/server';
import { queueService } from '@fasstech/rabbitmq-helper';
import { $Project, getProjectId, setProjectExternalId, updateProject } from '../entities/Project/index.mjs';
import { ExtendedProcessType } from './graphql/types/extended-process-type.mjs';
import { extendProcess } from './process/extend-process.mjs';

let serverConfig = {
  logger,
  graphql: { typeDefs: [ExtendedProcessType] },
  process: {
    resolveFirstView: async () => {
      return Promise.resolve('home');
    },
    extendWith: extendProcess
  },
  session: {
    validateProjectId: async ({ projectId }) => {
      const project = await $Project(projectId);
      return project != null;
    },
    resolveProjectFromContext: async (args) => {
      let externalId;

      if (getEnv('SECURE_SESSION')) {
        externalId = args.externalId;
      } else {
        const { getMockContext } = await import('../mocks/context.mjs');
        externalId = getMockContext().externalId;
      }

      let project = await $Project({ externalId });

      if (project == null) {
        project = await $Project();
        if (externalId != null) project = setProjectExternalId(externalId, project);
        project = await updateProject(project);
      }

      return getProjectId(project);
    }
  }
};

await startServer(serverConfig);

// Register a consumer to handle `events` messages
queueService.consumeMessage(`${getEnv('OAV_ID')}.events`, 0, handleTask);

Dans cet exemple :

lorsque SECURE_SESSION vaut true, le contexte client résolu par Fasst Sessions est consommé pour en extraire l'externalId ;

sinon, un contexte simulé (mocks/context.mjs) est utilisé, ce qui permet de décrocher sans jeton en développement ;

le projet est récupéré s'il existe, créé sinon ;

le consommateur AMQP est enregistré pour recevoir les évènements de tâches.

Démarrage de la partie serveur

npm run start-server:dev

Cette commande applique les migrations en attente (migrate:dev) puis démarre l'application Express (server:dev), qui lit ses variables depuis le fichier .env.

[info] Les variables d'environnement sont validées au démarrage. Un OAV mal configuré s'arrête immédiatement plutôt que de démarrer dans un état incohérent : le journal indique alors la variable fautive.

Démarrage de la partie client

npm run front:dev

Cette commande démarre le serveur de développement Vite. Par défaut, le client est servi sur le port 8000.

Décrochage sur l'OAV

Le décrochage est la phase d'entrée dans le parcours : le contexte client est résolu, le projet est déterminé et la première vue est calculée.

Avec un jeton

Récupérez un jeton d'authentification auprès du service Fasst Sessions :

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

L'application est alors accessible à l'adresse :

http://localhost:8000/?token=<GENERATED_TOKEN>

Les métadonnées transmises lors de la génération du jeton constituent le contexte client : elles sont restituées à la fonction resolveProjectFromContext.

Sans jeton

En développement, définir SECURE_SESSION=false dans le fichier .env désactive la résolution du contexte auprès de Fasst Sessions. L'application est alors accessible directement :

http://localhost:8000/

Dans ce mode dégradé, le contexte client est simulé dans le corps de la fonction resolveProjectFromContext.

[warn] SECURE_SESSION est ignorée en production : le décrochage y est toujours réalisé en mode sécurisé.

Ports utilisés

Élément	Port par défaut
Client Vite	8000
Serveur Express	Valeur de la variable PORT.
Fasst Sessions	3005
PostgreSQL	5432
OIP Headless	Défini par la variable OIP_API_URL.

Pour aller plus loin

Section	Contenu
Vérification et dépannage	Contrôle du bon fonctionnement de l'installation et résolution des erreurs courantes.
Conventions	Arborescence, nommage et traitement du code généré.
Guides	Procédures pas à pas, orientées tâche.
Cas d'usages	Scénarios complets combinant plusieurs mécanismes.

Résumé

Les services annexes se démarrent avec docker compose up -d ;

les trois fonctions de décrochage doivent être implémentées dans server/index.mjs avant tout démarrage du serveur ;

npm run start-server:dev applique les migrations puis démarre l'application Express, npm run front:dev démarre le client ;

le décrochage s'effectue avec un jeton émis par Fasst Sessions, ou sans jeton lorsque SECURE_SESSION=false en développement.