DRAFT: O3 EMR How-To Guide Outline
ABOUT: Michael Bontyes & Grace Potma are collaborating here to assemble the ideal How-To outline, so we can improve / evolve what is currently at om.rs/o3setup.
Decision Making | Review O3 | Install O3 | Configure O3 | Integrate O3 w/ other systems | Customizing & Developing on O3 | Maintaining O3 |
---|---|---|---|---|---|---|
Others:
- Finding Providers
- National Implementations
Implementation Team, trying to decide:
- Should we use the OpenMRS EMR?
- What are the advantages?
- How mature is the solution? Where is it currently used? Success stories?
- What features does it offer?
- What steps can we expect in the transition?
ICT members of the team. They have additional questions like:
- Is there a comparison of what we have now vs what comes w/ O3?
- What is already done in O3?
- How can we try this out quickly, ourselves? How do we:
- Set it up?
- Make it look more familiar to the users - eg colors, logos? UI? Content?
- Set up the sections and forms our users, our departments need?
- What if we want to build our own features?
- Who can we turn to for help?
- What do we do if we see gaps?
Configuration and deployment questions
- Run O3 on Docker (as the web server approach is suggested rather than OpenMRS SDK)
- Use the Demo version - ok
- Use a fresh installation without demo data - how to?
- How to specify the O3 version and where to find the WAR file - how to?
- How to fork O3 and build your custom Docker images (recommended approach by Ian and Raff, rather than using host volumes)
- Fork O3
- Modify Dockerfiles
- CD/CI pipelines
- Commit images
- Update docker-compose.yml
- Configure the backend modules
- Find modules and generate OMODS https://addons.openmrs.org/search
- Add modules in the configuration file - ok
- Locally compile OMOD from GitHub repo using Docker image
docker run --rm -v "$(pwd)":/opt/maven -w /opt/maven maven:3.8.6-openjdk-18-slim mvn clean install
- Configure the frontend modules
- Find modules and generate their packages (distro.properties) - ok
- Add modules in the configuration file (import-map.json or spa-build-config.json) - ok
- Manually fetch module:
curl -H "Accept: application/vnd.github+json" -H "Authorization: token ____________" -L -o module.zip "https://api.github.com/repos/openmrs/openmrs-esm-module-management-app/actions/artifacts/338768959/zip" - Create or modify frontend modules (https://github.com/openmrs/openmrs-esm-template-app for example)
- Yarn Install, dev, and build
- Npx assemble - local package option: http://%22@openmrs/esm-template-app%22:%20%22file:///User/ibacher/openmrs-esm-template-app/dist%22,,
Source Assemble: https://github.com/openmrs/openmrs-esm-core/blob/304fd2e7d7f20e85cf8151453e67baddf84794ab/packages/tooling/openmrs/src/commands/assemble.ts#L124 - Yarn Publish or use
- Generate distribution (using survey or config mode) - DEV
- 1. Build the frontend app
npx openmrs build
npx --legacy-peer-deps openmrs@next build --target dist --fresh (if conflicts or errors) - 2. Assemble frontend module (define spa path in spa-build-config.json)
define needed frontend modules in spa-build-config.json
npx openmrs assemble --mode config --config spa-build-config.json - 3. mount dist as a volume (in docker-compose)
- ./frontend/dist/:/usr/share/nginx/html/ - 4. commit and tag docker container (optional)
- 1. Build the frontend app
- Generate Docker image - DEPLOY
- 1. define needed frontend modules in spa-build-config.json
2. docker build -t michaelbontyes/o3_frontend:0.1 .
- Github action
https://github.com/marketplace/actions/build-and-push-docker-images
Configure the frontend UI
Logo Filename Modify logo style Main navigation Modify - Modify the UI (navigation, slots, widgets) using a custom-config.json - ok
- Dev in Docker: - ./config/custom-ui-config.json:/usr/share/nginx/html/custom-ui-config.json
- Modify the style of the UI using a custom-style.css - how to?
- Modify the logo and images of the UI - how to?
- Configure the content
- How to manage metadata?
- Where to define the content of the modules - in progress
- Registration (field mapping + configuration)
https://github.com/openmrs/openmrs-esm-patient-management/tree/main/packages/esm-patient-registration-app- Basic info
- Identifiers
- Address hierarchy
- Relationships
- Lists
- How to filter by location or privileges
- Queues
- How to define queries and automatically populate them?
- How to filter by location or privileges
- Registration (field mapping + configuration)
- How to manage forms + validation + calculated field - how to in O3 UI or Ampath? Form bank > Form Bank
- How to use field validation (for email and phone number for example) - how to?
- How to use Initializer configuration files - ok - how to reload? run startup.sh
- How to use OpenConceptLab for concept management - bugs/errors to investigate
- How to populate a source
- How to create collections
- How to reuse existing concepts from other sources
- How to map concepts to standardized concepts (CIEL, ICD, SNOMED)
- How to sync concepts in OpenMRS 3
- Using the Initializer module
- Using the sync module
- How to use Liquibase - how to? Using a module or iniz extend?
- Configure the language
- Administration language - how to?
- UI language - how to?
- Form language - how to?
- Manage O3 and patient data
- How to manage backups - how to?
- How to sync data across environments - how to?
- How to anonymize data - how to?
- How to print a patient file for handover purposes or data regulation compliance? - how to?
- Integrate O3 with DHIS2
- Integrate O3 with Superset dashboard
- CD-CI pipelines
- Github actions
- Containerization
- Run docker-compose
- Orchestration
- K8s dashboard
sudo kubeadm init --control-plane-endpoint=__.westeurope.cloudapp.azure.com
- K8s dashboard
What is the recommended practice to modify and reload configuration files within Docker infra (initiated with the 3.x docker-compose) for:
Config Scope Path Existing documentation File example OpenMRS WAR files OpenMRS Core /openmrs/distribution/openmrs_core path for war file? needed for distro Initializer files Locations, Programs, Concepts, etc. /openmrs/distribution/openmrs_config configuration
reload without restart O3?Modules + OMOD files ID Gen, Appointments, Cohort, OCL, etc.
Data filter?
/openmrs/distribution/openmrs_modules distro.properties
Repos for OMODs? Or OMOD generation best practice?OWAs files /openmrs/distribution/openmrs_owas SPA modules esm-patient-chart-app
form builderspa-build-config.json? (this is where the O3 RefApp configures which apps to use: https://github.com/openmrs/openmrs-distro-referenceapplication/blob/main/frontend/spa-build-config.json) import-map.json
/usr/share/nginx/html/importmap.json ? > web app config modulesmodules minified?
/etc/nginx/nginx.conf > server config
SPA UI config Patient chart order JSON path? to overwrite default config or customize one? https://spa-modules.nyc3.digitaloceanspaces.com/@openmrs/config/config.json
in /usr/share/nginx/html/config.jsonLocalization files for OpenMRS Admin translations /openmrs/l18n ? locale_en.json Localization files for O3 UI Transifex? path? ? Liquibase files Create users? path? ? Runtime properties path? openmrs-distro.properties Theming files like logos and icons openmrs_logo_white.gif path? startup.sh OMRS home, config folder, modules, database config, catalina options, server startup /usr/local/tomcat/startup.sh
in backend containerImage layers? path? config? - VIM in container? > -u root
- OCL org and source creation
- Options to map custom configuration within vanilla O3 containers to be validated:
- Option 1: Docker commits - push : ok
Option 2: Map the backend container in the docker-compose.yml with:
backend: image: openmrs/openmrs-reference-application-3-backend:${TAG:-nightly} depends_on: - db volumes: - ./distro:/openmrs/distribution
- Option 3: Sync with a GitHub repository within startup.sh?
- What is the recommended practice to back up or sync O3 data across environments? (also for organization-specific demos for example)
- How to start with a vanilla O3 setup? (No demo data, no unnecessary modules, etc.)