OZ-468: Add docs to create own distribution. (#4)

ozone-his · Mar 6, 2024 · 4669cb8 · 4669cb8
1 parent 27abf5c
commit 4669cb8
Show file tree

Hide file tree

Showing 3 changed files with 95 additions and 3 deletions.
diff --git a/docs/create-distro.md b/docs/create-distro.md
@@ -0,0 +1,92 @@
+# Create Your Own Distribution of Ozone HIS
+
+## Why your own distribution?
+
+Beyond experimenting with the Quick Start guide, implementers and integrators 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.
+
+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
+
+!!! tip "Prequisites"
+
+    Install [Git](https://github.com/git-guides/install-git), [Maven](https://www.baeldung.com/install-maven-on-windows-linux-mac) Maven and [Docker Compose](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:
+```xml
+<profiles>
+  <profile>
+    <id>ozone</id>
+    <repositories>
+      <repository>
+        <id>archetype</id>
+        <url>https://nexus.mekomsolutions.net/repository/maven-public</url>
+        <releases>
+          <enabled>true</enabled>
+          <checksumPolicy>fail</checksumPolicy>
+        </releases>
+        <snapshots>
+          <enabled>true</enabled>
+          <checksumPolicy>warn</checksumPolicy>
+        </snapshots>
+      </repository>
+    </repositories>
+  </profile>
+</profiles>
+
+<activeProfiles>
+  <activeProfile>ozone</activeProfile>
+</activeProfiles>
+```
+
+### 2) Generate the archetype
+
+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 
+```
+
+This will prompt you for several key variables for your Maven project:
+
+| Prompt variable    | Sample value     | Explanation                                                                                                                                                                                             |
+|--------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `distributionName` | `Ozone Gruzinia` | A name for your distribution. For example, a reference Ozone implementation for the imaginary country of Gruzinia could be named "Ozone Gruzinia".                                                      |
+| `groupId`          | `gz.moh`         | The [Maven group ID](https://maven.apache.org/guides/mini/guide-naming-conventions.html) that will be used for the implementation artifact. For "Ozone Gruzinia" this might be something like `gz.moh`. |
+| `artifactId`       | `ozone-gruzinia` | The [Maven artifact ID](https://maven.apache.org/guides/mini/guide-naming-conventions.html) that will be used for the implementation artifact. For "Ozone Gruzinia" this might be `ozone-gruzinia`.     |
+| `package`          | `gz.moh`         | A required property, but not used. To make it easy just accept the default value, which should default to be the same as the `groupId`.                                                                 |
+| `version`          | `1.0.0-SNAPSHOT` | The version number for the distribution, it starts by default at `1.0.0-SNAPSHOT`.                                                                                                                      |
+
+
+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
+```
+
+## Available commands
+
+|Action|Command|
+|:----|:----|
+|Build the distribution|<pre>./scripts/mvnw clean package</pre>|
+|Run the distribution|<pre>source target/go-to-scripts-dir.sh<br/><br/>./start-demo.sh</pre>|
+|Stop the distribution|<pre>./stop-demo.sh</pre>|
+|Destroy the distribution|<pre>./destroy-demo.sh</pre>|
+
+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.
diff --git a/docs/impl-guide.md → docs/override-configs.md b/docs/impl-guide.md → docs/override-configs.md
@@ -1,6 +1,5 @@
-# Implementer Guide
-
 !!! info "🚧 Work In Progress"
+
 Coming soon:  
  - Using the Ozone Maven archetype  
  - Using the Maven parent  

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,7 +4,8 @@ repo_name: ozone-his/ozone
 nav:
   - Implementers:
     - Quick Start: 'index.md'
-    - Implementer Guide: 'impl-guide.md'
+    - Create Your Own Distribution: 'create-distro.md'
+    - Override Inherited Configs: 'override-configs.md'
   - Users:
     - Overview: 'users/overview.md'
     - Single Sign-on: 'users/sso.md'