OZ-279: Implementer docs structured as evaluate/adopt/deploy.

docs/implementers/backup-restore.md

@@ -0,0 +1 @@
+# <small>:construction:</small> Backup & Restore

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 apps themselves, configuring integrations between the apps and enabling or disabling apps.
+
+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 app 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 apps "as is".
+
+
+!!! warning ""
+
+    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.
+
+## 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:
+

docs/implementers/configure-integrations.md

@@ -0,0 +1 @@
+# <small>:construction:</small> Configuring Integrations

docs/create-distro.md → 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 <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://github.com/git-guides/install-git)
     - [:simple-apachemaven: Maven <small>:fontawesome-solid-arrow-up-right-from-square:</small>](https://www.baeldung.com/install-maven-on-windows-linux-mac)
     - [:simple-docker: Docker Compose <small>:fontawesome-solid-arrow-up-right-from-square:</small>](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|<pre>./scripts/mvnw clean package</pre>|Assembles and packages your distribution, incorporating any configurations and customizations you've applied.|
-|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 apps 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 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.

docs/implementers/enable-central-auth.md

@@ -0,0 +1 @@
+# <small>:construction:</small> Enable Central Authorization

docs/implementers/enable-sso.md

@@ -0,0 +1 @@
+# <small>:construction:</small> Configuring Single Sign-On