Configuration et validation

10 min

Vue d'ensemble

La configuration d'un OAV repose sur quatre mécanismes complémentaires :

Mécanisme	Fichier	Rôle
Déclaration des valeurs	.env, .env.dist	Porte les valeurs de configuration en développement.
Validation	env-vars.yml	Décrit les variables attendues et déclenche la vérification au démarrage.
Exposition au client	vite.config.js	Rend visibles côté navigateur les valeurs qui le nécessitent.
Lecture applicative	getEnv	Accès unifié aux variables consolidées depuis le code serveur.

flowchart LR
    A[Container Startup] --> B[Environment Variable Validation]
    B --> C[Applying Migrations]
    C --> D[Starting the Express Server]

Fichier .env

Génération

Le fichier .env est généré par la commande oip-tools init à partir du modèle .env.dist présent dans le projet. Les valeurs de OAV_ID et OIP_API_KEY y sont générées et injectées.

Il est lu par la commande server:dev, elle-même appelée par start-server:dev.

Règles d'usage

Fichier	Versionné	Contenu
.env.dist	Oui	Liste des variables attendues, sans valeur sensible. Il documente la configuration nécessaire au projet.
.env	Non	Valeurs locales, dont des secrets. Il ne doit jamais être poussé sur le dépôt.

[warn] Toute nouvelle variable introduite dans le projet doit être ajoutée à .env.dist : c'est le seul document qui permette à un autre développeur de reconstituer une configuration complète.

En production

En production, aucun fichier .env n'est utilisé : les variables sont injectées dans le conteneur par l'orchestrateur. Le même artefact Docker est ainsi déployé sur tous les environnements.

Validation au démarrage

Les variables d'environnement sont vérifiées au démarrage du serveur, à partir du fichier env-vars.yml situé à la racine du projet. Cette vérification est réalisée par la bibliothèque @fasstech/checkenv.

Elle intervient dans la première phase de la fonction start exportée par @fasstech/oip-starter-utils/server, avant toute initialisation de l'application Express.

[warn] Une variable obligatoire absente ou invalide interrompt le démarrage. C'est un comportement voulu : un OAV mal configuré s'arrête plutôt que de démarrer dans un état incohérent.

Lecture des variables côté serveur

La fonction getEnv, exportée par @fasstech/oip-starter-utils/server, donne accès aux variables consolidées au démarrage. Elle est à préférer à un accès direct à process.env.

import { getEnv } from '@fasstech/oip-starter-utils/server';

if (getEnv('SECURE_SESSION')) {
  // Secure mode: the client context has been resolved by the sessions service
}

const eventsQueue = `${getEnv('OAV_ID')}.events`;

Exposition des variables au client

Le navigateur n'a pas accès aux variables d'environnement du serveur. Les valeurs nécessaires au client sont injectées à la construction du paquet, via la section define du fichier vite.config.js.

Variable d'environnement	Constante exposée	Nécessité
CLIENT_ID	__CLIENT_ID__	Toujours.
CLIENT_SECRET	__CLIENT_SECRET__	Toujours.
SERVER_URL	__SERVER_URL__	Uniquement pour un projet multi-origines.

import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    // ...
    define: {
      __CLIENT_ID__: JSON.stringify(env.CLIENT_ID),
      __CLIENT_SECRET__: JSON.stringify(env.CLIENT_SECRET),
      __SERVER_URL__: JSON.stringify(env.SERVER_URL)
    }
  };
});

[warn] Ces valeurs sont figées dans le paquet client au moment du build et sont donc lisibles par n'importe quel utilisateur. N'exposez jamais d'autre secret par ce mécanisme.

Valeurs typiques par environnement

Variable	Développement local	Production
NODE_ENV	Toute valeur autre que production.	production
SECURE_SESSION	false	Ignorée : toujours active.
SECURE_COOKIE	false	true
SECURE_WS	false	true
LOGGER_LEVEL	DEBUG	ERROR
SERVER_URL	Non renseignée.	Renseignée si le projet est multi-origines.

Résumé

En développement, la configuration vit dans .env, généré à partir de .env.dist ; en production, elle est injectée par l'orchestrateur ;

.env.dist est versionné et fait office de documentation de la configuration, .env ne l'est jamais ;

le fichier env-vars.yml décrit les variables attendues et déclenche leur validation au démarrage par @fasstech/checkenv ;

côté serveur, les variables se lisent avec getEnv ; côté client, seules CLIENT_ID, CLIENT_SECRET et SERVER_URL sont exposées via vite.config.js.