Configuration et validation
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. |
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.
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)
}
};
});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.