Configuration d’une instance de O3

Ce guide est destiné aux développeurs qui souhaitent configurer une instance de O3. En termes généraux, il existe deux approches pour configurer une instance de O3:

• Utiliser le SDK OpenMRS
• Utiliser Docker

Utilisation du SDK OpenMRS

Prérequis

Ces prérequis sont expliqués en détail dans le wiki du SDK .

• Assurez-vous d’avoir installé Apache Maven .

• Assurez-vous d’avoir une instance MySQL ou MariaDB prise en charge par la distribution O3 que vous choisissez.

• Utilisez un JDK LTS actuel pris en charge par cette distribution. Le Dockerfile actuel de l’application de référence construit et exécute l’application avec Amazon Corretto 21; Java 21 est donc le meilleur point de départ pour les travaux O3 actuels.

• Assurez-vous que votre variable d’environnement $JAVA_HOME est définie et qu’elle pointe vers le JDK que le SDK doit utiliser. Si vous avez la bonne version de Java installée mais que $JAVA_HOME ne pointe pas vers elle, vous pouvez essayer d’ajouter l’alias suivant à votre fichier .zshrc (ou .bashrc si vous utilisez Bash):

    alias mvn='JAVA_HOME="$(/usr/libexec/java_home -v 21)" mvn'

mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

mvn openmrs-sdk:setup

mvn openmrs-sdk:run

Dépannage de l’approche SDK

• Si vous rencontrez des problèmes, assurez-vous d’abord que Maven, le SDK OpenMRS, Java et la version de votre base de données correspondent à la distribution O3 que vous avez sélectionnée.

Utilisation de Docker

Prérequis

• Assurez-vous d’avoir Docker Desktop  ou Docker Compose (v2)  installé sur votre machine.

Suivez les étapes suivantes pour configurer une nouvelle instance de O3 sur votre machine à l’aide de Docker:

docker compose -f docker-compose.yml up -d

git fetch --tags
git tag --sort=-v:refname | head
TAG=<release-tag> docker compose -f docker-compose.yml up -d

curl -f http://localhost/openmrs/health/started

while [[ "$(curl -s -o /dev/null -w '%{http_code}' http://localhost/openmrs/health/started)" != "200" ]]; do sleep 10; done

Exécution d’une image Docker O3 sur une base de données existante

Pour exécuter l’image Docker O3 sur une base de données existante, faites ce qui suit:

services:
  gateway:
    image: openmrs/openmrs-reference-application-3-gateway:${TAG:-qa}
    restart: "unless-stopped"
    depends_on:
      - frontend
      - backend
    ports:
      - "80:80"
 
  frontend:
    image: openmrs/openmrs-reference-application-3-frontend:${TAG:-qa}
    restart: "unless-stopped"
    environment:
      SPA_PATH: /openmrs/spa
      API_URL: /openmrs
      SPA_CONFIG_URLS: /openmrs/spa/config-core_demo.json
      SPA_DEFAULT_LOCALE:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      timeout: 5s
    depends_on:
      - backend
 
  backend:
    image: openmrs/openmrs-reference-application-3-backend:${TAG:-qa}
    restart: "unless-stopped"
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: host.docker.internal
      OMRS_CONFIG_CONNECTION_DATABASE: openmrs
      OMRS_CONFIG_CONNECTION_USERNAME: ${OMRS_DB_USER:-openmrs}
      OMRS_CONFIG_CONNECTION_PASSWORD: ${OMRS_DB_PASSWORD:-openmrs}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/openmrs"]
      timeout: 5s
    volumes:
      - openmrs-data:/openmrs/data
 
volumes:
  openmrs-data: ~

Dépannage de l’approche Docker

• Si vous rencontrez des problèmes liés au démon Docker, assurez-vous que le démon fonctionne correctement.

• Si vous rencontrez un problème sous Windows concernant une version trop basse de WSL pour supporter l’exécution de la build dockerisée, suivez les instructions du message d’erreur pour mettre à jour votre version de WSL. Une fois cela fait, assurez-vous de redémarrer Docker Desktop ou le démon Docker.

• Si vous rencontrez des erreurs de permission après avoir exécuté docker compose up, vous pourriez être confronté à des volumes orphelins laissés par une exécution précédente de Docker Compose. C’est un problème connu avec les volumes Docker. Exécutez la commande suivante pour supprimer tous les volumes orphelins:

  docker compose down -v --remove-orphans

  Cette commande:

  • Arrête les conteneurs en cours d’exécution définis dans le fichier Docker compose.
  • Supprime les conteneurs.
  • Supprime les réseaux créés par le Docker compose.
  • Supprime les volumes associés aux conteneurs.
  • Supprime tous les conteneurs orphelins (conteneurs qui n’étaient pas définis dans le docker-compose.yml mais font partie du projet Docker Compose).

Mise à jour des métadonnées

En fonction de vos besoins, vous souhaiterez peut-être personnaliser les configurations et les métadonnées telles que les concepts, les types de visites, les types de rencontres, les emplacements, etc. qui sont chargées par le module d’initialisation. Lors de la personnalisation de ces métadonnées, construisez l’image Docker localement et utilisez cette image locale pour que les modifications soient affichées dans l’instance. Le dépôt de l’application de référence inclut docker-compose.override.yml, qui ajoute des contextes de construction locaux pour les services gateway, frontend et backend lorsque vous exécutez Compose depuis l’arborescence source clonée.

Étape 1: Arrêter votre instance

Si votre instance O3 est en cours d’exécution, arrêtez-la en exécutant:

docker compose down

Cette commande arrête les conteneurs actuels sans supprimer vos volumes, garantissant ainsi la conservation de vos données.

Étape 2: Construire l’image Docker locale

Pour refléter les métadonnées mises à jour dans votre instance, vous devrez construire une image Docker locale. Assurez-vous que vos fichiers de configuration respectent les conventions acceptées pour chaque configuration , car des formats incorrects pourraient empêcher l’apparition des métadonnées dans l’instance comme prévu.

TAG=your-custom-tag docker compose build

Remplacez your-custom-tag par un tag unique de votre choix.

Étape 3: Exécuter l’instance avec l’image mise à jour

Ensuite, démarrez votre instance en utilisant l’image locale construite en exécutant:

TAG=your-custom-tag docker compose -f docker-compose.yml up -d

Assurez-vous que l’argument passé à la variable TAG correspond au tag que vous avez utilisé à l’étape précédente. Cette commande lance l’instance en utilisant votre image locale au lieu d’en tirer une de Docker Hub.

Étape 4: Attendez que l’instance se lance

Enfin, suivez l’Étape 4 du guide de configuration et attendez que votre instance se lance complètement avec les métadonnées mises à jour.

Préparation pour la production

Par défaut, l’arborescence source de la RefApp construit le frontend avec les versions taguées next des modules frontend  et de l’app shell . Cela signifie qu’une image construite localement utilise les dernières versions pré-release disponibles. Les versions pré-release sont publiées sur NPM chaque fois qu’un commit est fusionné dans la branche main; elles ne sont donc pas recommandées pour une utilisation en production.

{
  "frontendModules": {
    "@openmrs/esm-active-visits-app": "x.y.z",
    "@openmrs/esm-appointments-app": "x.y.z"
    // ... autres modules frontend
  }
}

  ...
  ARG APP_SHELL_VERSION=x.y.z
  ...

Prochaines étapes

Une fois que vous avez configuré votre instance O3, il y a plusieurs choses que vous pourriez vouloir faire, y compris:

• Configurer un certificat TLS pour votre instance. Cela est important si vous envisagez d’exécuter votre instance en production. Vous pouvez utiliser un service comme Let’s Encrypt  pour obtenir un certificat TLS gratuit.

• Changer la langue par défaut de votre instance. Vous pouvez le faire en naviguant dans la section Administration de l’interface utilisateur OpenMRS héritée et en modifiant la langue par défaut.

• Personnaliser O3. Vous pouvez ajuster votre branding, configurer des modules, et plus encore. Consultez le guide Vue d’ensemble de la configuration pour plus de détails.

• Assurer le bon fonctionnement de vos modules (cela est pertinent uniquement si vous configurez O3 sur une base de données existante). Vous pouvez utiliser la page Gérer les modules dans l’interface d’administration héritée pour vérifier si les modules fonctionnent correctement.

• Tester diverses fonctionnalités - essayez d’enregistrer un patient et de lancer son dossier médical. Recherchez des erreurs dans la console ou des erreurs dans l’interface utilisateur. Vous pourriez également vouloir vérifier les erreurs dans l’onglet réseau des outils de développement de votre navigateur. Si vous n’avez pas le module fhir en cours d’exécution, vous devriez vous attendre à rencontrer des problèmes lors du rendu de la bannière du patient et de la plupart des autres widgets dans le dossier médical, car les éléments du dossier médical dépendent d’un UUID patient valide, et l’objet patient est récupéré via un point de terminaison FHIR.

• Réfléchir à la façon de configurer vos formulaires dans O3. Les nouveaux formulaires O3 sont généralement des schémas JSON conformes à ce schéma standard  et rendus par le React Form Engine d’O3. O3 peut aussi afficher des formulaires HTML Form Entry configurés via l’app Patient Forms, donc la conversion n’est requise que lorsque vous souhaitez déplacer ces formulaires vers le workflow schéma JSON et Form Engine. Consultez le générateur de formulaires intégré dans O3 pour avoir une idée de l’apparence de ce format. L’éditeur de schémas vous permet de créer un nouveau formulaire en utilisant une ébauche de schéma factice. Pour en savoir plus sur les formulaires dans O3, lisez la recette Construire des formulaires à l’aide du générateur de formulaires O3.

  ℹ️

  Un module OpenMRS existe pour convertir des schémas d’entrée de formulaire HTML en schémas JSON compatibles avec le schéma standard O3 à l’adresse suivante: https://github.com/openmrs/hfe-o3-form-schema-converter . Actuellement, des travaux sont en cours pour améliorer l’outil. Consultez le README du dépôt pour savoir ce qui est possible. Voir aussi le guide Convertir les formulaires d’entrée de formulaire HTML en O3.

Liens utiles

• Documentation SDK OpenMRS 
• Documentation pour implémentateurs O3  (la plupart du contenu de ce guide a été inclus dans ce guide)