OZ-279: How to customize distro + enabling/disabling components.

ozone-his · Jul 19, 2024 · b43dcfe · b43dcfe
1 parent b31a966
commit b43dcfe
Show file tree

Hide file tree

Showing 8 changed files with 225 additions and 30 deletions.
diff --git a/docs/configuring-components.md b/docs/configuring-components.md
@@ -0,0 +1,44 @@
+# <small>:construction:</small> Configuring HIS Components
+
+You will find a `configs` folder within the skeleton project generated by the Ozone Maven Archetype. This folder is subdivided into subfolders, with each subfolder corresponding to a component of the Ozone HIS distribution. It should look something like this depending on the components available:
+
+```bash
+ configs/
+    ├── erpnext
+    ├── odoo
+    ├── openmrs
+    ├── senaite
+    └── superset
+```
+
+Each component-specific subfolder can be used to provide the configuration files for that component, overriding its default configuration.
+
+!!! warning ""
+
+    Each component's default configuration is the responsibility of the component's open-source community.
+
+    Ozone HIS provides these configurations "as is", they are not modified or maintained by the Ozone development team.
+
+## Overriding the ERPNext Config
+
+## Overriding the Odoo Config
+
+## Overriding the OpenMRS Config
+
+To assist implementers, the OpenMRS config is already structured with multiple subfolders that gather in one place all the essential configurations of OpenMRS 3:
+```bash
+   ├── openmrs
+         ├── frontend_assembly
+         ├── frontend_config
+         └── initializer_config
+```
+
+### `frontend_assembly`
+
+### `frontend_config`
+
+### `initializer_config`
+
+## Overriding the SENAITE Config
+
+## Overriding the Superset Config
diff --git a/docs/create-distro.md b/docs/create-distro.md
@@ -16,7 +16,7 @@ Ozone provides a series Apache Maven-based tools to facilitate the assembly of y
 
 The Ozone Maven Archetype generates a foundational skeleton project, providing a customizable base for any specific implementation requirements.
 
-### 1) Configure Maven
+## **1** &nbsp; Configure Maven
 
 Edit your Maven `settings.xml` file (usually located at `~/.m2/settings.xml`) and add the following block to it:
 ```xml
@@ -45,7 +45,7 @@ Edit your Maven `settings.xml` file (usually located at `~/.m2/settings.xml`) an
 </activeProfiles>
 ```
 
-### 2) Generate the archetype
+## **2** &nbsp; Generate the archetype
 
 Use Maven's archetype tools to generate a new Ozone implementation project structure:
 
@@ -67,19 +67,19 @@ This will prompt you for several key variables for your Maven project:
 This will create a bare-bones Ozone implementation project that should look like this:
 ```bash
 ozone-gruzinia/
-├── README.md
-├── config
-│     └── openmrs
-│         ├── frontend_config
-│         └── initializer_config
-├── pom.xml
-├── readme
-│     └── impl-guide.md
-└── scripts
-    ├── mvnw
-    ├── mvnw.cmd
-    ├── mvnwDebug
-    └── mvnwDebug.cmd
+  ├── README.md
+  ├── configs
+  │     └── openmrs
+  │         ├── frontend_config
+  │         └── initializer_config
+  ├── pom.xml
+  ├── readme
+  │     └── impl-guide.md
+  └── scripts
+      ├── mvnw
+      ├── mvnw.cmd
+      ├── mvnwDebug
+      └── mvnwDebug.cmd
 ```
 
 ## Available commands
@@ -90,6 +90,4 @@ ozone-gruzinia/
 |Access start/stop/destroy commands|<pre>source target/go-to-scripts-dir.sh</pre>|Navigates to the directory containing the scripts for starting, stopping, and destroying the distribution, making these commands readily accessible.|
 |**Start** the distribution|<pre>./start-demo.sh</pre>|Initiates and launches all components of the Ozone HIS, bringing up the system.|
 |**Stop** the distribution|<pre>./stop-demo.sh</pre>|Gracefully halts all Ozone HIS services, effectively shutting down the system.|
-|**Destroy** the distribution|<pre>./destroy-demo.sh</pre>|Completely removes the distribution, clearing all its components and data, ideal for resetting the system or rectifying persistent issues ahead of a restart or a rebuild and restart.|
-
-You are now ready to tailor Ozone to fit your specific requirements. Proceed to the following page for guidance on how to override default configurations.
+|**Destroy** the distribution|<pre>./destroy-demo.sh</pre>|Completely removes the distribution, clearing all its components and data, ideal for resetting the system or rectifying persistent issues ahead of a restart or a rebuild and restart.|
diff --git a/docs/customize-ozone.md b/docs/customize-ozone.md
@@ -0,0 +1,56 @@
+# Customizing Ozone HIS
+
+After you have generated your own distribution of Ozone HIS with the Ozone Maven Archetype, the next step is to explore the possibilities for customizing your distribution to meet your specific needs and specifications.
+
+There are four main areas of customization and configuration available to you to do so:
+
+!!! abstract "Configurability in Ozone HIS"
+
+    1. Customizing the default distribution behavior.
+    2. Enabling & disabling HIS components.
+    3. Configuring HIS components.
+    4. Configuring the EIP layer.
+
+## Ozone HIS is a Maven Distribution
+
+It is an essential prerequisite to understand that your distribution of Ozone HIS is managed as a [:simple-apachemaven:Maven <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://maven.apache.org/what-is-maven.html) project.
+
+Every standard Ozone HIS distribution is generated with the _Ozone Maven Archetype_ as a child of the _Ozone Maven Parent_. The default behavior of such a distribution is a combination of
+
+* What is inherited from the parent.
+* What is auto-generated within the archetype.
+
+What constitutes your software distribution of Ozone HIS is stated and defined in the main [Maven POM <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html) file of your distribution, the one that has been was generated by the archetype. 
+
+!!! tip "**Did you know?**"
+
+    Your distribution POM file is **a manifest** that states {==all that makes your Ozone HIS distribution==}.
+
+## Customizing the Maven Distribution
+
+Practically every element of the POM file can be modified to achieve the changes you wish to make to your Ozone HIS distribution. We will not attempt to define an exhaustive list of all possible customizations, as virtually anything can be achieved with Maven. Instead, we will use this space to build an inventory of useful examples of such customizations that have occured through real-world use cases.
+
+### Adding further software dependencies
+
+!!! example "Adding custom OpenMRS backend modules"
+
+    The KenyaHMIS Ozone distribution required additional OpenMRS backend modules (JAR files) beyond those provided by default in OpenMRS. This can be achieved by adding Maven dependencies in the main POM file of the Ozone HIS distribution.
+
+    See [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L132-L186) how this can be done.
+
+### Overriding the version of default software dependencies
+
+!!! example "Using another version of the OpenMRS Initializer module"
+
+    The KenyaHMIS Ozone distribution needed to temporarily depend on a bleeding-edge version of the Initializer module rather than the released version packaged with OpenMRS by default. This can be achieved in two steps:
+
+    1. Excluding the packaged Initializer JAR file, see [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L229).
+    2. Re-adding a dependency on the desired version of Initializer, see [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L125-L129).
+
+### Excluding default configuration files
+
+!!! example "Ignoring default OpenMRS backend configuration files"
+
+    The KenyaHMIS Ozone distribution did not require several OpenMRS backend configuration files that come by default with OpenMRS. Since these configuration files are already packaged through the OpenMRS dependency, one way to handle this is to exclude the unwanted configuration files from the package.
+
+    See [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L210-L227) how this can be done.
diff --git a/docs/config-points.md → docs/eip-config-points.md b/docs/config-points.md → docs/eip-config-points.md
@@ -1,4 +1,4 @@
-# <small>:construction:</small> Configuration Points
+# <small>:construction:</small> EIP Configuration Points
 
 In this section, we provide a comprehensive list of configuration points available in Ozone, organized by EIP services and thereby grouped by pairs of components.
 
@@ -17,7 +17,7 @@ In this section, we provide a comprehensive list of configuration points availab
 - _Possible values:_<br/>
 The time in milliseconds. Defaults to 30000 – Controls the polling interval for the `eip-keycloak-superset` service, which regularly fetches the set of roles from Superset to synchronize them with Keycloak.
 
-!!! tip "Sample configuration:"
+!!! example "Sample configuration:"
 
     ```java
     superset.polling-interval=30000
@@ -35,7 +35,7 @@ The time in milliseconds. Defaults to 30000 – Controls the polling interval fo
     * [x] `false` – An OpenMRS patient is synchronised as an ERPNext customer when a first billable item is ordered from OpenMRS.
     * [ ] `true` – An OpenMRS patient is always synchronised as an ERPNext customer.
 
-!!! tip "Sample configuration:"
+!!! example "Sample configuration:"
 
     ```java
     erpnext.openmrs.enable.patient.sync=false

diff --git a/docs/enabling-components.md b/docs/enabling-components.md
@@ -0,0 +1,94 @@
+# Enabling & Disabling HIS Components
+
+Ozone uses Docker by default and its Docker Compose setup is stated as a dependency of the distribution by relying on the Ozone Docker Compose project:
+
+```xml
+<dependency>
+  <groupId>com.ozonehis</groupId>
+  <artifactId>ozone-docker-compose</artifactId>
+  <type>zip</type>
+</dependency>
+```
+
+!!! question "What if Docker can't be used?"
+
+    Ozone's default deployment mechanism could be changed by depending on another deployment mechanism project than Ozone Docker Compose. Such alternatives, that are yet to be developed, could leverage Kubernetes, bare metal installation, Puppet, Vagrant, etc.
+
+!!! info ""
+
+    This guide will run you through the process of enabling and disabling Ozone HIS components when using Docker Compose as the deployment mechanism.
+
+## Introducing `docker-compose-files.txt`
+
+This key configuration file in the Ozone Docker Compose project serves as the default inventory of the various Docker Compose files that will be run when launching Ozone HIS. Its default content may look like this:
+
+```text
+docker-compose-common.yml
+docker-compose-odoo.yml
+docker-compose-openmrs.yml
+docker-compose-senaite.yml
+```
+
+* The `docker-compose-common.yml` file defines shared services and configurations that are used across the entire Ozone HIS Docker Compose setup. It includes common settings and dependencies needed by multiple components.
+* The `docker-compose-odoo.yml` file handles spinning up Odoo, `docker-compose-openmrs.yml` takes care of OpenMRS, and `docker-compose-senaite.yml` is responsible for SENAITE.
+
+!!! info ""
+
+    There will be a default Docker Compose file provided by Ozone for each supported component of the Ozone HIS FOSS ecosystem.
+
+## Overriding `docker-compose-files.txt`
+
+It is possible to define another setup than the Ozone default with your own version of `docker-compose-files.txt` that you would place here, where "`ozone-gruzinia`" is the top level folder of your distribution Maven project:
+
+```bash
+ozone-gruzinia
+    └── scripts
+           └── docker-compose-files.txt
+```
+
+When doing so, it will be your override file located in the `scripts` directory that will be taken into account, rather than the default file provided by Ozone Docker Compose. This allows you to enable or disable the HIS components of your choice by modifying your version of `docker-compose-files.txt`.
+
+For instance, the following setup would disable Odoo and use ERPNext as the ERP system within Ozone HIS:
+
+!!! tip "Changing the default ERP system to ERPNext in `docker-compose-files.txt`"
+    ```text
+    docker-compose-common.yml
+    {==docker-compose-erpnext.yml==}
+    docker-compose-openmrs.yml
+    docker-compose-senaite.yml
+    ```
+
+This was achieved by removing `docker-compose-odoo.yml` (disabling Odoo) and adding `docker-compose-erpnext.yml` (enabling ERPNext).
+
+!!! example "OpenMRS Distro HIS with ERPNext"
+
+    The OpenMRS Distro HIS is a starter distribution of OpenMRS that demonstrates integration with other digital health software, such as an ERP system. It uses ERPNext instead of Odoo, which is Ozone's default ERP component. To achieve this, it overrides `docker-compose-files.txt` as described above.
+
+    See [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/openmrs/openmrs-distro-his/blob/379f0b600493dac04b46b8283f97bc5d9e7aa089/scripts/docker-compose-files.txt) how this is done.
+
+## Further customizing Docker Compose files with `docker-compose-override.yml`
+
+It is also possible to provide an additional `docker-compose-override.yml`[^override] to tweak the default Docker Compose files provided by Ozone Docker Compose without modifying them directly. This pattern is crucial for ensuring that implementers can utilize the default Docker Compose files provided by Ozone as much as possible before needing to maintain their own versions of them.
+
+[^override]: The YAML file name doesn't matter and can be chosen freely. Additionally, you can have as many additional Docker Compose files as desired.
+
+!!! tip "Adding a `docker-compose-override.yml` in `docker-compose-files.txt`"
+    ```text
+    docker-compose-common.yml
+    docker-compose-odoo.yml
+    docker-compose-openmrs.yml
+    docker-compose-senaite.yml
+    {==docker-compose-override.yml==}
+    ```
+
+### Examples of customizations with `docker-compose-override.yml`
+
+!!! example "Adding OpenMRS frontend configuration files"
+
+    The OpenMRS Distro HIS requires to run its own configuration of the OpenMRS frontend. See [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/openmrs/openmrs-distro-his/blob/379f0b600493dac04b46b8283f97bc5d9e7aa089/scripts/docker-compose-override.yml#L5) how this can be done.
+
+!!! example "Bespoke initialisation of OpenMRS' MySQL database"
+
+    This bespoke configuration ensures that the MySQL service starts with specific settings tailored for the KenyaHMIS project. It also initializes the database with necessary SQL scripts that update and configure the database schema and data according to the project’s requirements.
+
+    See [here <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/scripts/docker-compose-override.yml) how this can be done.
diff --git a/docs/override-configs.md b/docs/override-configs.md
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -2,6 +2,14 @@
   color: #007d79;
 }
 
+.md-typeset .admonition {
+  font-size: 100%;
+}
+
+.md-typeset .admonition-title {
+  font-weight: 500;
+}
+
 .md-typeset {
   font-size: 140%;
 }

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,8 +6,10 @@ nav:
   - System Implementers:
     - Quick Start: 'index.md'
     - Create Your Own Distribution: 'create-distro.md'
-    - "<span style='color:#b0b0b0;font-style:italic'>Override Inherited Configs</span>": 'override-configs.md'
-    - "<span style='color:#b0b0b0;font-style:italic'>Configuration Points</span>": 'config-points.md'
+    - Customizing Ozone HIS: 'customize-ozone.md'
+    - Enabling & Disabling HIS Components: 'enabling-components.md'
+    - "<span style='color:#b0b0b0;font-style:italic'>Configuring HIS Components</span>": 'configuring-components.md'
+    - "<span style='color:#b0b0b0;font-style:italic'>EIP Configuration Points</span>": 'eip-config-points.md'
   - Functional Users:
     - Overview: 'users/index.md'
     - "<span style='color:#b0b0b0;font-style:italic'>SSO & Auth</span>": 'users/auth.md'