This repository defines the OpenMRS distribution for Zanmi Lasante (PIH Haiti). It packages together the PIH EMR parent distribution, Zanmi Lasante-specific content, and the PIH EMR frontend into a single deployable artifact. For more background on OpenMRS distributions, see the OpenMRS wiki.
| Directory | Description |
|---|---|
content/ |
Zanmi Lasante-specific OpenMRS content package (Initializer and O3 configuration files) |
distro/ |
Distribution definition — resolves all component versions into openmrs-distro.properties |
| Component | Artifact |
|---|---|
| PIH EMR parent distro | org.openmrs.distro:pihemr |
| PIH EMR shared content | org.pih.openmrs:pihemr-content |
| Zanmi Lasante content | org.pih.openmrs:zl-content |
| PIH EMR frontend | org.pih.openmrs:openmrs-frontend-pihemr |
Component versions are defined in distro/pom.xml and resolved into distro/openmrs-distro.properties at build time.
| Site | PIH Config |
|---|---|
hum-ci |
mirebalais,mirebalais-humci |
ci |
haiti,haiti-hsn,haiti-local-idgen |
haitihivtest |
haiti,haiti-hiv,haiti-hiv-ci |
zl-ci |
haiti,haiti-central,haiti-local-idgen |
These are the four sites with automated CI/CD (Bamboo deploy triggers). Nightly seed images are
built per base config lineage rather than per site: hum-ci (mirebalais,mirebalais-humci) uses
the mirebalais lineage, published as partnersinhealth/zl-emr-seed-mirebalais, while ci,
haitihivtest, and zl-ci all use the haiti lineage, published as
partnersinhealth/zl-emr-seed-haiti. See CI and Publishing below. Many
other pih-config-*.json profiles exist under content/configuration/backend_configuration/pih/
for Zanmi Lasante's production and field-site deployments — those are deployed through separate,
existing infrastructure outside this repository's GitHub Actions.
Developers can use the OpenMRS SDK to set up, update, and run local OpenMRS instances. All normal OpenMRS SDK commands are supported.
One can also use the openmrs-sdk command supplied by the openmrs-contrib-distro-tools CLI if that is more convenient.
Follow the installation instructions in that repo first if you wish to use this command.
Consult the openmrs-contrib-distro-tools README
for more information on each supported command and configuration option.
Whenever one creates a new SDK server, there are several options one has to configure it. One must specify the
distribution to install, the PIH Config to use, the Tomcat port, the Debug port, the Java version, and whether to
connect to an existing database or to create a new one, and whether to do so in the default SDK Docker container,
one's own Docker container, or in a native MySQL server. The openmrs-sdk documentation provides a full list of
these options, which can be set via environment variables.
The least configuration required to get up and running is to specify the PIH Config only, which will use all other defaults including the database, which will use the built-in SDK Docker container.:
PIH_CONFIG=haiti,haiti-central,haiti-local-idgen \
openmrs-sdk create <server-id>
Many developers maintain their own MySQL Docker container into which they maintain their various SDK servers. For example,
one might have an existing MySQL Docker container named mysq56 exposing port 3308, and with a root password of password.
To use this container instead, simply add the appropriate additional environment variables as documented in the README:
PIH_CONFIG=haiti,haiti-central,haiti-local-idgen \
DB_CONTAINER=mysql56 \
DB_PORT=3308 \
DB_PASSWORD=password \
openmrs-sdk create <server-id>
This is just a thin wrapper around the native OpenMRS SDK maven command:
openmrs-sdk run <server-id>Note
For those who are familiar with previously running ./pihemrDeploy.sh from openmrs-distro-pihemr,
this is the equivalent of that, with the addition that this will also update the configuration and frontend.
openmrs-sdk update <server-id>Unlike a full update, this only updates the configuration files and is intended to be faster, suitable for more rapid iteration of content changes for testing.
Note
For those who are familiar with previously running ./install.sh from openmrs-config-zl, this is the
equivalent of that, with the exception that this will not automatically build in local changes to openmrs-config-pihemr.
One will first need to run a mvn clean install in openmrs-config-pihemr to incorporate local changes from it.
openmrs-sdk update-config <server-id>For each supported configuration profile, an example environment file is provided in the repo root to get started quickly.
Because this file is found in the distribution repository, it is assumed that this is checked out on your machine, and
that openmrs-docker commands are running from the root of the distribution repository — it sets DISTRO_SOURCE_DIR
to this location. If you're using it as an example for running elsewhere, you may need to change or remove that.
To use the example environment file for zl-ci to get up and running with a new instance:
source zl-ci.env
openmrs-docker create zl-ci
openmrs-docker zl-ci initialize # Optional, but speeds up initial startup
openmrs-docker zl-ci start
openmrs-docker zl-ci wait # Tails logs until OpenMRS is ready, then exitsOnce created, day-to-day commands only need the instance name:
openmrs-docker zl-ci stop
openmrs-docker zl-ci logs
openmrs-docker zl-ci destroyThe same pattern applies to hum-ci.env, ci.env, and haitihivtest.env — substitute the instance name accordingly.
CI is handled by GitHub Actions. On every push to master, the Build and deploy workflow:
- Builds and publishes the Maven artifact to Maven Central as
org.pih.openmrs:zl-distro. - Builds and pushes a multi-platform Docker image (amd64 + arm64) to Docker Hub at
partnersinhealth/zl-emr, tagged with bothlatestand the Maven project version. - Fires the existing Bamboo
hum-ci,ci,haitihivtest, andzl-cideploy triggers, exactly as the legacydeploy.ymlworkflow did.
A separate Build seeded images workflow runs nightly and publishes pre-initialized seed images to Docker Hub for the two base config lineages: partnersinhealth/zl-emr-seed-haiti (general Haiti/ZL-network config) and partnersinhealth/zl-emr-seed-mirebalais (Mirebalais hospital config).
A separate Update Versions workflow runs hourly and automatically commits any available snapshot dependency updates to master.