From 51712f178abd76b9a1415ac370b0a511df62758f Mon Sep 17 00:00:00 2001 From: rbuisson Date: Tue, 11 Feb 2025 18:05:14 +0100 Subject: [PATCH 1/2] OZ-279: Kick start implementer docs --- docs/implementers/backup-restore.md | 1 + docs/implementers/configure-apps.md | 131 ++++++++++++++++++ docs/implementers/configure-integrations.md | 1 + docs/{ => implementers}/create-distro.md | 77 ++++++---- docs/implementers/enable-central-auth.md | 1 + docs/implementers/enable-sso.md | 1 + .../{ => implementers}/enabling-components.md | 0 docs/implementers/intro.md | 16 +++ docs/implementers/monitor.md | 1 + docs/implementers/quick-start.md | 10 ++ docs/implementers/specs.md | 1 + docs/implementers/start-stop.md | 10 ++ docs/implementers/troubleshoot.md | 1 + docs/index.md | 3 - mkdocs.yml | 24 +++- 15 files changed, 243 insertions(+), 35 deletions(-) create mode 100644 docs/implementers/backup-restore.md create mode 100644 docs/implementers/configure-apps.md create mode 100644 docs/implementers/configure-integrations.md rename docs/{ => implementers}/create-distro.md (61%) create mode 100644 docs/implementers/enable-central-auth.md create mode 100644 docs/implementers/enable-sso.md rename docs/{ => implementers}/enabling-components.md (100%) create mode 100644 docs/implementers/intro.md create mode 100644 docs/implementers/monitor.md create mode 100644 docs/implementers/quick-start.md create mode 100644 docs/implementers/specs.md create mode 100644 docs/implementers/start-stop.md create mode 100644 docs/implementers/troubleshoot.md diff --git a/docs/implementers/backup-restore.md b/docs/implementers/backup-restore.md new file mode 100644 index 0000000..a05d199 --- /dev/null +++ b/docs/implementers/backup-restore.md @@ -0,0 +1 @@ +# :construction: Backup & Restore diff --git a/docs/implementers/configure-apps.md b/docs/implementers/configure-apps.md new file mode 100644 index 0000000..517aa6f --- /dev/null +++ b/docs/implementers/configure-apps.md @@ -0,0 +1,131 @@ +# Configuring Apps + +Now that you have successfully created your Ozone distribution, the next step is to customize and configure it to meet your specific needs. This process involves three main aspects: configuring the applications themselves, configuring integrations between the applications and enabling or disabling applications. + +This page focuses specifically on configuring the Ozone applications. + +The Ozone ecosystem strongly advocates for configuring your server through configuration files rather than alternative methods such as database archives, SQL queries, or manual UI configuration. This approach ensures that you can consistently replicate your production (or soon-to-be production) instance at any time. +By adopting this practice, you gain the flexibility to create multiple environments for various purposes, including development, testing, demonstration, and training, without relying on or anonymizing a production database. Furthermore, this method empowers implementers to maintain full control over the configuration, enhancing overall system management and reproducibility. + +Within the skeleton project generated by the Ozone Maven Archetype, you'll find a `configs/` directory. This directory is organized into subfolders, each corresponding to a component of the Ozone HIS distribution. + +By default, the `configs/` directory contains only the `openmrs/` sub-folder as an example. However, as you progressively add more configurations, it will gradually expand to include one folder for each enabled application in your Ozone distribution. For example: + +```bash + configs/ + ├── erpnext + ├── openmrs + ├── senaite + └── superset + ... +``` + +Each app-specific subfolder can be used to provide the configuration files for that app, thereby overriding the default configuration of the app. + +Without providing any particular files your distro will run off of the default apps configurations. Ozone itself is mostly not overriding any configuration, but uses the applications "as is". + + +!!! 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 OpenMRS 3 Config + +This section assumes knowledge of: + +- OpenMRS module Initializer +- OpenMRS 3 frontend configuration & architecture + +To assist implementers, the OpenMRS 3 config in Ozone is already structured with multiple subfolders that outline the essential configurations: +```bash + ├── openmrs + ├── frontend_assembly + ├── frontend_config + └── initializer_config +``` + +### The `frontend_assembly/` folder + +The `frontend_assembly/` folder is meant to contain only one file: `spa-assemble-config.json`. In this file, one can specify frontend modules to exclude from the inherited OpenMRS Reference Application, new ones to add or versions override. This configuration is optional and no file can be provided if you do not want or need to override the frontend modules. + +Eg: +```json +{ + "frontendModules": { + "@kenyaemr/esm-care-panel-app": "5.1.1-pre.157" + }, + "__comment": "", + "frontendModuleExcludes": [ + "@openmrs/esm-service-queues-app" + ] +} +``` + +_Technical note:_ The `spa-assemble-config.json` is merged with the default [assembly file](https://github.com/openmrs/openmrs-distro-referenceapplication/blob/main/frontend/spa-assemble-config.json) from OpenMRS Reference Application at build time by a custom build script provided in Ozone, [build-openmrs-frontend.groovy](https://github.com/ozone-his/ozone/blob/main/scripts/openmrs/frontend_assembly/build-openmrs-frontend.groovy) + + +### The `frontend_config/` folder + +The `frontend_config/` folder is where to specify OpenMRS 3 frontend configurations. This could be one or multiple JSON files. +By default, a child Ozone distribution will come with 2 config files, directly inherited from the Ozone parent distribution. +``` +frontend_config/ +├── ozone-frontend-config-sso.json +└── ozone-frontend-config.json +``` + +Those can be overridden by simply creating a file of the same name in your own distribution. +Or you can create a new file to bring distro-specific configurations on top of the existing ones. Doing so will require to set a particular environment variable so to inform OpenMRS frontend of this newly introduced configuration file. For example, `config.json`. + +The variable to override is named `SPA_CONFIG_URLS`. It consists of a comma separated list of file paths. +Create a new `.env` file in the `scripts/` folder of your distribution with any name. For example, `override.env`. +Then set the value of the variable there. For example: + +```properties +SPA_CONFIG_URLS=/openmrs/spa/configs/ozone-frontend-config.json,/openmrs/spa/configs/config.json +``` +The above example tells OpenMRS to load the default Ozone file `ozone-frontend-config.json`, as well your custom `config.json` file. +They will be loaded in the order provided. + +### The `initializer_config/` folder + +The third folder in the OpenMRS configuration is `initializer_config/`. This folder is designated to contain all configuration files for the OpenMRS backend. The OpenMRS Initializer module reads from this directory and applies the specified configurations to the system. These configurations encompass various elements such as Visit Types, Concepts, Roles, Privileges, and Clinical forms, among others. + +For comprehensive information on the Initializer's functionality and usage, refer to the detailed documentation available in the OpenMRS Initializer GitHub repository. + +👉 [GitHub: OpenMRS Initializer](https://github.com/mekomsolutions/openmrs-module-initializer/) + + +## Overriding the SENAITE Config + +### The `initializer_config/` folder + +In its standalone form, SENAITE does not include pre-configured settings or a built-in mechanism for loading configurations. Implementers typically need to manually configure the system through the user interface and retain this database for the initial production deployment, or alternatively, develop a custom add-on containing the desired configurations. + +However, SENAITE's underlying framework, Plone, offers functionality for loading configuration archives. To leverage this capability within the Ozone ecosystem, we've developed a Plone Initializer plugin. This plugin enables SENAITE to utilize configuration loading features when integrated with Ozone. + +The configuration process still requires initial setup via the user interface, followed by exporting these settings. Once exported, the configurations will be automatically applied during subsequent deployments, streamlining the setup process for multiple instances. + +:construction: TODO: Guide for exporting the configuration archive. + +## Overriding the Odoo Config + +Like SENAITE, Odoo lacks a implementer-friendly mechanism for loading configurations by default. Implementers typically resort to creating custom add-ons (requiring coding skills) or manual UI configuration, which poses challenges for environment reproducibility. + +However, Odoo's underlying framework does support file imports. To capitalize on this feature, Ozone utilizes the Odoo Initializer add-on. This tool enables the loading of CSV or XML files from a designated configuration folder to Odoo. + +For in-depth information on the Odoo Initializer's functionality and usage, consult the documentation available in its GitHub repository. + +👉 [GitHub: Odoo Initializer](https://github.com/mekomsolutions/odoo-initializer/) + + +## Overriding the Superset Config + +:construction: + +## Overriding the ERPNext Config + +:construction: + diff --git a/docs/implementers/configure-integrations.md b/docs/implementers/configure-integrations.md new file mode 100644 index 0000000..d6e1b22 --- /dev/null +++ b/docs/implementers/configure-integrations.md @@ -0,0 +1 @@ +# :construction: Configuring Integrations \ No newline at end of file diff --git a/docs/create-distro.md b/docs/implementers/create-distro.md similarity index 61% rename from docs/create-distro.md rename to docs/implementers/create-distro.md index decf408..ff4e2b5 100644 --- a/docs/create-distro.md +++ b/docs/implementers/create-distro.md @@ -4,18 +4,49 @@ Beyond experimenting with the Quick Start guide, implementers of Ozone HIS will soon discover the need to provide their own configurations and possibly bespoke customizations to Ozone HIS. We recommend to do so through creating and managing your own distribution of Ozone HIS. +Adopting a distribution architecture for Ozone offers several compelling advantages: + +### Enhanced Packaging and Configuration Management + +By creating your own distribution (e.g., using Maven Archetype), you inherit Ozone's robust packaging concepts. This approach enables proper versioning of configurations, facilitating controlled and agile deployments. + +### Flexible Inheritance Structure + +A distribution architecture allows for a multi-layered structure, enabling hierarchical configuration management. For instance, you can: + +- Establish country-level configurations +- Inherit and customize these at the program level +- Further refine settings for specific facilities + +### Seamless Upgradability + +By utilizing the distribution mechanism, you incorporate the main Ozone as a dependency, building upon it rather than forking the codebase. This approach mitigates the risk of isolation and ensures easier upgrades. + +### Simplified Adoption and Focus + +Ozone handles complex build logic and base configurations, allowing you to concentrate on adapting the system to your specific requirements. This approach significantly reduces the learning curve and implementation time. + +### Enhanced Collaboration and Community Impact + +By leveraging the upstream Ozone development, all users benefit from community-driven improvements. This collaborative model makes it easier for individuals and organizations to contribute meaningfully to the Ozone ecosystem. + + + +## Create your own "child" distribution + Ozone provides a series Apache Maven-based tools to facilitate the assembly of your own tailored HIS distribution. This starts with the _Ozone Maven Archetype_. -## The Ozone Maven Archetype + +### The Ozone Maven Archetype + + +The Ozone Maven Archetype generates a foundational skeleton project, providing a customizable base for any specific implementation requirements. !!! tip "Software Prequisites" - - [:simple-git: Git :fontawesome-solid-arrow-up-right-from-square:](https://github.com/git-guides/install-git) - [:simple-apachemaven: Maven :fontawesome-solid-arrow-up-right-from-square:](https://www.baeldung.com/install-maven-on-windows-linux-mac) - [:simple-docker: Docker Compose :fontawesome-solid-arrow-up-right-from-square:](https://docs.docker.com/compose/install/) -The Ozone Maven Archetype generates a foundational skeleton project, providing a customizable base for any specific implementation requirements. - ### 1) Configure Maven Edit your Maven `settings.xml` file (usually located at `~/.m2/settings.xml`) and add the following block to it: @@ -50,7 +81,9 @@ Edit your Maven `settings.xml` file (usually located at `~/.m2/settings.xml`) an Use Maven's archetype tools to generate a new Ozone implementation project structure: ```bash -mvn org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate -DarchetypeArtifactId=maven-archetype -DarchetypeGroupId=com.ozonehis +mvn org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \ + -DarchetypeArtifactId=maven-archetype \ + -DarchetypeGroupId=com.ozonehis ``` This will prompt you for several key variables for your Maven project: @@ -68,28 +101,20 @@ This will create a bare-bones Ozone implementation project that should look like ```bash ozone-gruzinia/ ├── README.md -├── config -│ └── openmrs -│ ├── frontend_config -│ └── initializer_config -├── pom.xml -├── readme -│ └── impl-guide.md -└── scripts - ├── mvnw - ├── mvnw.cmd - ├── mvnwDebug - └── mvnwDebug.cmd +├── assembly.xml +├── configs +│   └── openmrs +│   ├── frontend_config +│   └── initializer_config +└── pom.xml + ``` -## Available commands +Congratulations :clap:, you have created your child distribution of Ozone. Note that it does not configure or override anything. It is, at the moment, only plain Ozone. +Check out our next section to configure your distribution: -|Goal|Command|Explanation| -|:----|:----|:----| -|**Build** the distribution|
./scripts/mvnw clean package
|Assembles and packages your distribution, incorporating any configurations and customizations you've applied.| -|Access start/stop/destroy commands|
source target/go-to-scripts-dir.sh
|Navigates to the directory containing the scripts for starting, stopping, and destroying the distribution, making these commands readily accessible.| -|**Start** the distribution|
./start-demo.sh
|Initiates and launches all apps of the Ozone HIS, bringing up the system.| -|**Stop** the distribution|
./stop-demo.sh
|Gracefully halts all Ozone HIS services, effectively shutting down the system.| -|**Destroy** the distribution|
./destroy-demo.sh
|Completely removes the distribution, clearing all its apps and data, ideal for resetting the system or rectifying persistent issues ahead of a restart or a rebuild and restart.| +- [Configure Apps](./configure-apps.md) - White labeling, metadata configuration... +- [Configure Integrations](./configure-integrations.md) - Configure integration points, enable/disable integration routes... +- [Enable & Disable Apps Integrations](./enabling-components.md) - Define which app or integration should be run. -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. +Or if you want to try your distribution as such, jump right to [Start & Stop](./start-stop.md) page. diff --git a/docs/implementers/enable-central-auth.md b/docs/implementers/enable-central-auth.md new file mode 100644 index 0000000..55f38a2 --- /dev/null +++ b/docs/implementers/enable-central-auth.md @@ -0,0 +1 @@ +# :construction: Enable Central Authorization \ No newline at end of file diff --git a/docs/implementers/enable-sso.md b/docs/implementers/enable-sso.md new file mode 100644 index 0000000..07588fb --- /dev/null +++ b/docs/implementers/enable-sso.md @@ -0,0 +1 @@ +# :construction: Configuring Single Sign-On \ No newline at end of file diff --git a/docs/enabling-components.md b/docs/implementers/enabling-components.md similarity index 100% rename from docs/enabling-components.md rename to docs/implementers/enabling-components.md diff --git a/docs/implementers/intro.md b/docs/implementers/intro.md new file mode 100644 index 0000000..097aca7 --- /dev/null +++ b/docs/implementers/intro.md @@ -0,0 +1,16 @@ +This implementation guide is divided in 3 sections which correspond to the typical implementer approach: + +## 1. Evaluate +For those new to Ozone, this section outlines various assessment options. It includes: + +- A link to the online demo +- Instructions for running Ozone locally +- Guidance on using Ozone within a Gitpod environment + +## 2. Adopt +Once you've determined Ozone's suitability for your project, it's time to set up your environment. +First and foremost, you will want to create your own copy of Ozone (aka, distribution), so that you can configure it or customize it to your needs. This is essential to adopt Ozone. We have developed a comprehensive tool suite to facilitate implementers creating their own distribution. Such distribution will be at first, an empty shell that will just inherit a plain Ozone. Progressively, you will be able make it your own, but under the hood still depending on the most recent version of Ozone, directly benefiting from its new features and fixes. + +## 3. Deploy +Finally, once your software is ready and packaged, you can deploy it to your server. Ozone provides some utils scripts to help you with this. Additionally, it comes with backup and restore functionality as well as monitoring. We also provide in that section a page for common errors and troubleshooting tips. + diff --git a/docs/implementers/monitor.md b/docs/implementers/monitor.md new file mode 100644 index 0000000..e5ca29c --- /dev/null +++ b/docs/implementers/monitor.md @@ -0,0 +1 @@ +# :construction: Monitor diff --git a/docs/implementers/quick-start.md b/docs/implementers/quick-start.md new file mode 100644 index 0000000..604288a --- /dev/null +++ b/docs/implementers/quick-start.md @@ -0,0 +1,10 @@ +Before diving deeper into actually implementing Ozone, make sure you had gone through evaluating it. +Various options are available to you to do so: + +* Online Demo +* Run locally +* Run remotely on Gitpod + +Please open the [⚡️ Quick Start ⚡️](../index.md) page for instructions. + +Once done, you can come back to the Implementer docs and continue your journey with Ozone in the next section which will describe how to further adopt Ozone. diff --git a/docs/implementers/specs.md b/docs/implementers/specs.md new file mode 100644 index 0000000..1532db6 --- /dev/null +++ b/docs/implementers/specs.md @@ -0,0 +1 @@ +# :construction: Software & Hardware Requirements \ No newline at end of file diff --git a/docs/implementers/start-stop.md b/docs/implementers/start-stop.md new file mode 100644 index 0000000..220b28e --- /dev/null +++ b/docs/implementers/start-stop.md @@ -0,0 +1,10 @@ +# :construction: Start & Stop + + +|Goal|Command|Explanation| +|:----|:----|:----| +|**Build** the distribution|
./scripts/mvnw clean package
|Assembles and packages your distribution, incorporating any configurations and customizations you've applied.| +|Access start/stop/destroy commands|
source target/go-to-scripts-dir.sh
|Navigates to the directory containing the scripts for starting, stopping, and destroying the distribution, making these commands readily accessible.| +|**Start** the distribution|
./start-demo.sh
|Initiates and launches all apps of the Ozone HIS, bringing up the system.| +|**Stop** the distribution|
./stop-demo.sh
|Gracefully halts all Ozone HIS services, effectively shutting down the system.| +|**Destroy** the distribution|
./destroy-demo.sh
|Completely removes the distribution, clearing all its apps and data, ideal for resetting the system or rectifying persistent issues ahead of a restart or a rebuild and restart.| diff --git a/docs/implementers/troubleshoot.md b/docs/implementers/troubleshoot.md new file mode 100644 index 0000000..6e0be68 --- /dev/null +++ b/docs/implementers/troubleshoot.md @@ -0,0 +1 @@ +# :construction: Troubleshoot \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f3d2dc3..b01924d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,3 @@ -!!! info "" - - This section of the Ozone Docs is designed for **digital health technical implementers**, focusing on how to install, configure, and run the Ozone HIS. # Quick Start diff --git a/mkdocs.yml b/mkdocs.yml index 409c3d0..e8a7ca7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,13 +3,24 @@ site_url: https://docs.ozone-his.com repo_url: https://github.com/ozone-his/ozone-distro repo_name: ozone-his/ozone nav: + - Quick Start: 'index.md' + - System Implementers: - - Quick Start: 'index.md' - - Create Your Own Distribution: 'create-distro.md' - - Customizing Ozone HIS: 'customize-ozone.md' - - Enabling & Disabling HIS Components: 'enabling-components.md' - - "Configuring HIS Components": 'configuring-components.md' - - "EIP Configuration Points": 'eip-config-points.md' + - Introduction: 'implementers/intro.md' + - Evaluate: + - Quick Start: 'implementers/quick-start.md' + - Adopt Ozone: + - Create Your Own Distribution: 'implementers/create-distro.md' + - Configure Apps: 'implementers/configure-apps.md' + - Configure Integrations: 'implementers/configure-integrations.md' + - Enable & Disable Apps and Integrations: 'implementers/enabling-components.md' + - Deploy: + - Start & Stop: 'implementers/start-stop.md' + - Backup & Restore: 'implementers/backup-restore.md' + - Monitor: 'implementers/monitor.md' + - Troubleshoot: 'implementers/troubleshoot.md' + - Software & Hardware Requirements: 'implementers/requirements.md' + - Functional Users: - Overview: 'users/index.md' - "SSO & Auth": 'users/auth.md' @@ -41,6 +52,7 @@ theme: primary: custom logo: assets/logo.png favicon: assets/images/favicon.png + extra: homepage: https://www.ozone-his.com social: From 6334d87b3f8f6e6863784d15d896755bf4487728 Mon Sep 17 00:00:00 2001 From: rbuisson Date: Wed, 19 Feb 2025 16:47:59 +0100 Subject: [PATCH 2/2] OZ-279: Consitently use app as opposed to applications or components --- docs/configuring-components.md | 44 --------------- docs/customize-ozone.md | 56 ------------------- docs/implementers/configure-apps.md | 10 ++-- ...nabling-components.md => enabling-apps.md} | 0 mkdocs.yml | 2 +- 5 files changed, 6 insertions(+), 106 deletions(-) delete mode 100644 docs/configuring-components.md delete mode 100644 docs/customize-ozone.md rename docs/implementers/{enabling-components.md => enabling-apps.md} (100%) diff --git a/docs/configuring-components.md b/docs/configuring-components.md deleted file mode 100644 index 7f8410e..0000000 --- a/docs/configuring-components.md +++ /dev/null @@ -1,44 +0,0 @@ -# :construction: 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 \ No newline at end of file diff --git a/docs/customize-ozone.md b/docs/customize-ozone.md deleted file mode 100644 index 25d244f..0000000 --- a/docs/customize-ozone.md +++ /dev/null @@ -1,56 +0,0 @@ -# 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 :fontawesome-solid-arrow-up-right-from-square:](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 :fontawesome-solid-arrow-up-right-from-square:](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 :fontawesome-solid-arrow-up-right-from-square:](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 :fontawesome-solid-arrow-up-right-from-square:](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L229). - 2. Re-adding a dependency on the desired version of Initializer, see [here :fontawesome-solid-arrow-up-right-from-square:](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 :fontawesome-solid-arrow-up-right-from-square:](https://github.com/palladiumkenya/kenyahmis/blob/b24503fd623d6b9c06a94d1af3588c15b463abf6/pom.xml#L210-L227) how this can be done. \ No newline at end of file diff --git a/docs/implementers/configure-apps.md b/docs/implementers/configure-apps.md index 517aa6f..8aef114 100644 --- a/docs/implementers/configure-apps.md +++ b/docs/implementers/configure-apps.md @@ -1,15 +1,15 @@ # Configuring Apps -Now that you have successfully created your Ozone distribution, the next step is to customize and configure it to meet your specific needs. This process involves three main aspects: configuring the applications themselves, configuring integrations between the applications and enabling or disabling applications. +Now that you have successfully created your Ozone distribution, the next step is to customize and configure it to meet your specific needs. This process involves three main aspects: configuring the apps themselves, configuring integrations between the apps and enabling or disabling apps. -This page focuses specifically on configuring the Ozone applications. +This page focuses specifically on configuring the apps available in the Ozone ecosystem. The Ozone ecosystem strongly advocates for configuring your server through configuration files rather than alternative methods such as database archives, SQL queries, or manual UI configuration. This approach ensures that you can consistently replicate your production (or soon-to-be production) instance at any time. By adopting this practice, you gain the flexibility to create multiple environments for various purposes, including development, testing, demonstration, and training, without relying on or anonymizing a production database. Furthermore, this method empowers implementers to maintain full control over the configuration, enhancing overall system management and reproducibility. Within the skeleton project generated by the Ozone Maven Archetype, you'll find a `configs/` directory. This directory is organized into subfolders, each corresponding to a component of the Ozone HIS distribution. -By default, the `configs/` directory contains only the `openmrs/` sub-folder as an example. However, as you progressively add more configurations, it will gradually expand to include one folder for each enabled application in your Ozone distribution. For example: +By default, the `configs/` directory contains only the `openmrs/` sub-folder as an example. However, as you progressively add more configurations, it will gradually expand to include one folder for each enabled app in your Ozone distribution. For example: ```bash configs/ @@ -22,12 +22,12 @@ By default, the `configs/` directory contains only the `openmrs/` sub-folder as Each app-specific subfolder can be used to provide the configuration files for that app, thereby overriding the default configuration of the app. -Without providing any particular files your distro will run off of the default apps configurations. Ozone itself is mostly not overriding any configuration, but uses the applications "as is". +Without providing any particular files your distro will run off of the default apps configurations. Ozone itself is mostly not overriding any configuration, but uses the apps "as is". !!! warning "" - Each component's default configuration is the responsibility of the component's open-source community. + Each app's default configuration is the responsibility of its own open-source community. Ozone HIS provides these configurations "as is", they are not modified or maintained by the Ozone development team. diff --git a/docs/implementers/enabling-components.md b/docs/implementers/enabling-apps.md similarity index 100% rename from docs/implementers/enabling-components.md rename to docs/implementers/enabling-apps.md diff --git a/mkdocs.yml b/mkdocs.yml index e8a7ca7..3fc4b2e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,7 +13,7 @@ nav: - Create Your Own Distribution: 'implementers/create-distro.md' - Configure Apps: 'implementers/configure-apps.md' - Configure Integrations: 'implementers/configure-integrations.md' - - Enable & Disable Apps and Integrations: 'implementers/enabling-components.md' + - Enable & Disable Apps and Integrations: 'implementers/enabling-apps.md' - Deploy: - Start & Stop: 'implementers/start-stop.md' - Backup & Restore: 'implementers/backup-restore.md'