Créer une distribution

L’une des raisons pour lesquelles nous avons choisi ce type de modularisation dans l’espace frontal est de permettre une flexibilité maximale pour créer votre propre distribution. De cette façon, vous pouvez utiliser ce que vous trouvez utile et laisser tomber ce que vous n’aimez pas voir dans votre distribution.

Ce concept s’applique à presque tous les domaines, y compris, mais sans s’y limiter, les modules frontaux disponibles, l’enveloppe de l’application livrée et la méthode de distribution de l’application.

Ce guide vous explique comment créer une distribution O3 de A à Z, y compris la construction, les tests et le déploiement.

Prérequis

Avant de commencer, assurez-vous d’avoir:

• Node.js version 20.11 ou ultérieure installée. Le Dockerfile frontend de l’application de référence utilise actuellement Node 22. Nous recommandons d’utiliser nvm  ou fnm  pour gérer les versions de Node.js.
• npm (fourni avec Node.js) - Vous l’utiliserez pour exécuter l’outil CLI openmrs via npx
• Un backend OpenMRS - Vous aurez besoin d’un backend OpenMRS en cours d’exécution pour connecter votre distribution (pour les tests et la production)

Installation

L’outil CLI openmrs peut être exécuté sans installation en utilisant npx (qui fait partie de npm):

npx openmrs --help

Alternativement, vous pouvez l’installer globalement:

npm install -g openmrs

Ensuite, vous pouvez exécuter les commandes directement sans npx:

openmrs --help

Pour les environnements CI/CD, utilisez une version explicite du package openmrs, par exemple npx --legacy-peer-deps openmrs@<app-shell-version>, afin que le CLI et l’app shell utilisés par la construction soient reproductibles.

Démarrage rapide: Workflow complet

Voici un workflow complet étape par étape pour créer votre première distribution:

mkdir my-o3-distribution
cd my-o3-distribution

{
  "publicUrl": ".",
  "frontendModules": {
    "@openmrs/esm-patient-chart-app": "latest",
    "@openmrs/esm-patient-registration-app": "latest",
    "@openmrs/esm-home-app": "latest"
  },
  "frontendModuleExcludes": []
}

{
  "spaPath": "/openmrs/spa/",
  "apiUrl": "/openmrs/",
  "configUrls": [],
  "defaultLocale": "en",
  "importmap": "./spa/importmap.json",
  "routes": "./spa/routes.registry.json",
  "supportOffline": false
}

npx openmrs assemble --manifest --mode config --config spa-assemble-config.json --target ./spa

npx openmrs build --build-config spa-build-config.json --target ./spa

cd ./spa
python3 -m http.server 8080

Construction locale vs configuration CI

Vous pourriez être tenté de cloner le dépôt openmrs-esm-core pour construire votre distribution. Ne faites pas cela à moins que vous ne sachiez exactement pourquoi vous voulez travailler avec le dépôt. Le dépôt n’est là que pour le développement du Frontend OpenMRS. Il n’est pas là pour construire des distributions.

Pour construire votre propre distribution, un simple outil Node.js appelé openmrs a été créé. Il permet de

• créer une carte d’importation avec toutes les ressources pour les modules frontaux contenus (openmrs assemble)
• construire un nouveau shell pour héberger les modules frontaux (openmrs build)
• démarrer une session de débogage du shell et d’un module frontal (openmrs debug)
• démarrer une session de débogage d’un module frontal dans le shell (openmrs develop)
• démarrer localement le shell de l’application par défaut (openmrs start)

Pour créer une distribution, vous devez compléter deux étapes dans l’ordre:

1. Assembler la carte d’importation (openmrs assemble) - Ceci rassemble tous les actifs des modules frontaux et crée la carte d’importation et le registre des routes.
2. Construire le shell de l’application (openmrs build) - Ceci construit le shell de l’application qui hébergera vos modules frontaux, en utilisant la carte d’importation et les routes de l’étape 1.

La carte d’importation est utilisée pour définir quels modules frontaux sont inclus et où ces modules frontaux sont situés. L’étape de construction nécessite la sortie de l’étape d’assemblage.

Voici un exemple de workflow complet:

# Étape 1: Assembler les modules frontaux et créer la carte d'importation
openmrs assemble --manifest --mode config --config spa-assemble-config.json --target ./spa
 
# Étape 2: Construire le shell de l'application
openmrs build --build-config spa-build-config.json --target ./spa

Personnaliser la carte d’importation

En construisant le shell de l’application, vous obtiendrez déjà une version rudimentaire d’une carte d’importation, qui peut être utilisée à des fins de développement. En général, cependant, vous devriez fournir votre propre carte d’importation.

Une carte d’importation peut également être spécifiée sous la forme d’une URL. Par exemple, pour l’instance de développement à dev3.openmrs.org nous avons https://dev3.openmrs.org/openmrs/spa/importmap.json . Le contenu de cette carte d’importation est mis à jour dès qu’une mise à jour d’un module frontend officiel a été poussée. Ainsi, bien que cette carte d’importation puisse être utile pour le développement, elle doit être considérée comme instable. Évitez-la pour votre distribution ou pour toute application qui ne doit pas tomber en panne de manière inattendue.

Une carte d’importation personnalisée peut être créée à l’aide de la commande openmrs assemble. Si elle est lancée directement, la commande ouvrira une enquête en ligne de commande, vous guidant à travers les différentes options. Elle listera tous les modules frontaux d’OpenMRS qui peuvent être trouvés dans le registre NPM.

Pour des raisons de CI/CD, nous vous encourageons à utiliser un fichier de configuration spa-assemble-config.json à la place. Ce fichier définit les modules frontaux souhaités et configure l’ensemble du processus. Notez que spa-assemble-config.json est différent de spa-build-config.json, qui est utilisé pour les propriétés de configuration à l’exécution (voir le guide Vue d’ensemble de la configuration pour plus de détails).

Pour utiliser le fichier de configuration, exécutez:

openmrs assemble --mode config --config spa-assemble-config.json --target ./spa

Vous pouvez également spécifier des options supplémentaires:

• --target <répertoire>: Le répertoire cible où les artefacts rassemblés seront stockés (par défaut: dist)
• --fresh: Nettoyer le répertoire de sortie avant l’exécution
• --manifest: Générer un fichier manifeste avec les informations de version
• --mode config: Utiliser le mode fichier de configuration. Sans cette option, le CLI démarre le questionnaire interactif.

Le fichier peut ressembler à ce qui suit:

{
  "publicUrl": ".",
  "frontendModules": {
    "@openmrs/esm-patient-chart-app": "latest",
    "@openmrs/esm-patient-registration-app": "3.0.0"
  },
  "frontendModuleExcludes": []
}

Le tableau frontendModuleExcludes vous permet d’exclure des modules spécifiques qui pourraient être inclus en tant que dépendances d’autres modules. Ceci est utile lorsque vous souhaitez supprimer un module qui serait autrement inclus automatiquement.

Le publicUrl peut être important pour plus tard. Si les ressources rassemblées sont placées (et servies) dans le même dossier que les ressources de la SPA, alors . est bon. Si elles sont téléchargées vers un CDN, l’URL (de base) du CDN doit être définie.

Exemple:

{
  "publicUrl": "https://openmrs-cdn-example.com/mf",
  "frontendModules": {
    "@openmrs/esm-patient-chart-app": "latest",
    "@openmrs/esm-patient-registration-app": "3.0.0"
  }
}

Dans ce cas, le fichier importmap.json résultant pourrait ressembler à ce qui suit:

{
  "imports": {
    "@openmrs/esm-patient-chart-app": "https://openmrs-cdn-example.com/mf/openmrs-esm-patient-chart-app-3.2.1/openmrs-esm-patient-chart-app.js",
    "@openmrs/esm-patient-registration-app": "https://openmrs-cdn-example.com/mf/openmrs-esm-patient-registration-app-3.0.0/openmrs-esm-patient-registration-app.js"
  }
}

Dans les deux cas, la commande d’assemblage permet de s’assurer que tous les actifs sont correctement mis à disposition.

Construire le shell de l’application

Après avoir assemblé vos modules frontaux, vous devez construire le shell de l’application. Le processus de construction nécessite un fichier spa-build-config.json qui configure les propriétés d’exécution pour votre distribution.

Le fichier spa-build-config.json doit inclure:

{
  "spaPath": "/openmrs/spa/",
  "apiUrl": "/openmrs/",
  "configUrls": ["/openmrs/spa/config.json"],
  "defaultLocale": "en",
  "importmap": "./spa/importmap.json",
  "routes": "./spa/routes.registry.json",
  "supportOffline": false
}

Propriétés clés:

• spaPath: Le chemin où la SPA sera servie (par exemple, /openmrs/spa/)
• apiUrl: L’URL de l’API backend OpenMRS
• configUrls: Tableau d’URLs vers les fichiers de configuration JSON frontend
• defaultLocale: Code de langue par défaut (par exemple, en, fr)
• importmap: Chemin, URL ou JSON inline pour la carte d’importation créée par assemble. Les chemins relatifs sont résolus depuis le répertoire où vous exécutez la commande.
• routes: Chemin, URL ou JSON inline pour le registre des routes créé par assemble. Les chemins relatifs sont résolus depuis le répertoire où vous exécutez la commande.
• supportOffline: S’il faut activer le support hors ligne via un service worker

La CLI OpenMRS lit spa-build-config.json comme du JSON littéral. Elle ne développe pas les variables d’environnement shell dans ce fichier pendant openmrs build. Si vous construisez directement des fichiers statiques, placez les URLs finales dans le fichier JSON ou passez les options CLI correspondantes.

La distribution Reference Application utilise intentionnellement des valeurs de substitution comme $SPA_PATH, $API_URL et $SPA_CONFIG_URLS, car son conteneur Docker frontend remplace ces valeurs au démarrage:

{
  "spaPath": "$SPA_PATH",
  "apiUrl": "$API_URL",
  "configUrls": ["$SPA_CONFIG_URLS"],
  "defaultLocale": "$SPA_DEFAULT_LOCALE",
  "importmap": "$SPA_PATH/importmap.json",
  "routes": "$SPA_PATH/routes.registry.json",
  "supportOffline": false
}

Pour construire le shell de l’application, exécutez:

openmrs build --build-config spa-build-config.json --target ./spa

Options de construction supplémentaires:

• --target <répertoire>: Le répertoire cible (doit correspondre au répertoire cible d’assemblage)
• --fresh: Nettoyer le répertoire de sortie avant la construction
• --support-offline: Activer le support hors ligne (peut remplacer le fichier de configuration)

Après une construction réussie, votre répertoire ./spa contiendra:

• index.html - Le fichier HTML principal pour la SPA
• importmap.json - La carte d’importation créée par l’étape d’assemblage
• routes.registry.json - Le registre des routes créé par l’étape d’assemblage
• Les bundles JavaScript et autres actifs nécessaires pour exécuter l’application

Important: Si vous utilisez configUrls dans votre spa-build-config.json, vous devrez également vous assurer que ces fichiers de configuration JSON sont disponibles et servis avec vos fichiers construits. Par exemple, si votre configuration référence /openmrs/spa/config.json, ce fichier doit être accessible à cette URL lorsque la SPA se charge.

Servir votre distribution

Après avoir construit votre distribution, vous devez servir les fichiers construits à l’aide d’un serveur web. Les fichiers construits sont des actifs statiques qui peuvent être servis par n’importe quel serveur web (nginx, Apache, etc.).

Configuration de base

La façon la plus simple de servir votre distribution est d’utiliser un serveur de fichiers statiques. Les fichiers construits doivent être servis au chemin spécifié dans votre configuration spaPath (par exemple, /openmrs/spa/).

Considérations importantes:

1. Fichiers de configuration: Si vous utilisez configUrls dans votre spa-build-config.json, assurez-vous que ces fichiers de configuration JSON sont également accessibles via HTTP/HTTPS aux URLs spécifiées. La SPA les récupérera à l’exécution.

2. Connexion backend: Assurez-vous que votre serveur web peut proxy les requêtes API vers votre backend OpenMRS, ou configurez CORS sur votre backend pour autoriser les requêtes depuis votre domaine frontend.

3. Configuration du chemin: Le spaPath dans votre configuration de construction doit correspondre au chemin où vous servez les fichiers. Par exemple, si spaPath est /openmrs/spa/, votre serveur web doit servir les fichiers à ce chemin.

Exemple: Utiliser nginx

Voici une configuration nginx de base pour servir votre distribution:

server {
    listen 80;
    server_name localhost;
 
    # Servir la SPA à /openmrs/spa/
    location /openmrs/spa/ {
        alias /usr/share/nginx/html/;
        try_files $uri $uri/ /openmrs/spa/index.html;
    }
 
    # Proxy des requêtes API vers le backend OpenMRS
    location /openmrs/ {
        proxy_pass http://backend:8080/openmrs/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Test local

Pour tester votre distribution localement, vous pouvez:

1. Utiliser un serveur HTTP simple:

   cd ./spa
   python3 -m http.server 8080

   Cela sert le contenu de ./spa à http://localhost:8080/. Utilisez-le avec une construction dont le spaPath vaut /, ou passez à nginx/Docker lorsque vous devez conserver un chemin imbriqué comme /openmrs/spa/.

2. Utiliser la commande openmrs start pour le développement (bien que cela utilise une carte d’importation par défaut, pas votre carte personnalisée).

3. Utiliser Docker avec nginx, similaire à la configuration de la distribution de référence.

Déploiement

Pour les déploiements en production:

• Docker: Copiez le répertoire ./spa construit dans un conteneur nginx (voir le Dockerfile de la distribution de référence pour un exemple)
• Hébergement statique: Téléchargez le contenu du répertoire ./spa vers votre service d’hébergement statique (CDN, S3, etc.)
• Serveur web traditionnel: Copiez les fichiers vers la racine des documents de votre serveur web

N’oubliez pas de déployer également tous les fichiers de configuration JSON référencés dans vos configUrls et assurez-vous qu’ils sont accessibles aux URLs spécifiées.

Canary vs Stable

En ce qui concerne les versions, vous avez trois options:

• Choisir la balise latest (la plus récente)
• Aller vers la balise next.
• Aller vers une version spécifique (i.e., explicite)

En général, nous recommandons de rester sur des versions qui ne sont pas des versions de prévisualisation (par exemple, 3.2.1). Les versions de prévisualisation (par exemple, 3.2.1-pre.0) sont destinées au développement et peuvent ne pas être stables.

Pour créer une distribution fonctionnelle, l’idéal est de s’en tenir à un versionnage explicite des versions qui ne sont pas des versions d’aperçu. Si vous utilisez latest alors les modules frontaux individuels peuvent fonctionner comme prévu, mais des incompatibilités (par exemple, si un certain module frontal a été mis à jour mais est maintenant incompatible avec un autre module frontal que vous utilisez également) peuvent alors exister - ce qui nécessite des tests supplémentaires. Avec une version explicite, vous pouvez être sûr qu’un système qui fonctionne reste tel quel dans les scénarios de reconstruction.