chore: Improve documentation (#3)

Separated documentation into two sections: - Routine deployment and Extra modules deployment. - The `Routine deployment` contains the bare minimum documentation for setting up kenyaEMR - The `Extra modules deployment` section contains documentation for additional modules that can be added as part of KenyaEMR; thus, it builds on top of the `Routine deployment`.
savannahghi · Jan 31, 2024 · 3584619 · 3584619
1 parent 61eb6c6
commit 3584619
Showing 1 changed file with 77 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -24,24 +24,7 @@ KenyaEMR-v{x.y.z}.tar.xz
     |       └── *.sql (optional)
     ├── modules - OpenMRS module files (omod) that constitute this release.
     |   └── *.omod
-    ├── extra_modules - OpenMRS module files (omod) that are not part of official KenyaEMR release
-    |   └── module_x - Directory containing extra module, typically named same as <module_name>
-    |   |    └── migrations - Database migration files. Follows the same hierarchy as shown in parent folder
-    |   |       ├── install - SQL migration files to run during installation.
-    |   |       |   └── *.sql (optional)
-    |   |       ├── post_install - SQL migration files to run after installation.
-    |   |       |   └── *.sql (optional)
-    |   |       ├── upgrade - SQL migration files to run during an upgrade.
-    |   |       |   └── *.sql (optional)
-    |   |       └── post_upgrade - SQL migration files to run after an upgrade.
-    |   |       |   └── *.sql (optional)
-    |   |       module_x.omod - the actual omod file. Must be named as <module_name>.omod
-    |   └── module^n - Other extra modules will follow the same hierarchy as above.
-    |           └── migrations ...
-    |           |     ├── install
-    |           |           .......
-    |           |               ......
-    |           module^n.omod 
+    ├── extra_modules - For more details on this, see the section on `Adding extra-modules`
     ├── webapps - War files to deploy to a servlet container.
     |   └── openmrs.war - The OpenMRS war file.
     └── README.md - Readme file with additional info about this release (optional).
@@ -55,54 +38,110 @@ Things to note:
 
 ## Deployment
 
-This section lists the general steps to follow during the deployment of KenyaEMR. These are split into steps for a fresh installation and steps for an upgrade of an existing installation. Note that whatever is listed here are just the general guidelines of the steps to follow and might not be sufficient/accurate for each release. As such, whenever a release has deployment steps that deviate from what is listed here, that will always be indicated on the README file included in the release.
+This section lists the steps to follow during deployment of KenyaEMR. The steps are split into two sections: **Routine deployment** and **Extra modules deployment.** 
+Each section includes the actions for `fresh installation` and `upgrade` of an existing installation.
+Note that whatever is listed here are just the general guidelines of the steps to follow and might not be sufficient/accurate for each release. As such, whenever a release has deployment steps that deviate from what is listed here, that will always be indicated on the README file included in the release.
 
+## 1) Routine deployment
 ### Installation
 
 - Download the release archive from the [releases section](https://github.com/savannahghi/kenya-emr-releases/releases).
-- Unarchive the downloaded file into a temporary directory. We will refer to this directory as `keEMR-x.y.z`.
+- Unarchive the downloaded file into a temporary directory. We will refer to this directory as `kenyaEMR-x.y.z`.
 - Stop the target servlet container if running.
-- Copy the `openmrs.war` file from the `keEMR-x.y.z/webapps` directory into the webapps (or similar) directory of the servlet container.
+- Copy the `openmrs.war` file from the `kenyaEMR-x.y.z/webapps` directory into the webapps (or similar) directory of the servlet container.
 - Create an [OpenMRS data directory](https://wiki.openmrs.org/display/docs/Application+Data+Directory). We will refer to this directory as `oMRS_data_dir`.
-- Copy omods in `keEMR-x.y.z/extra_modules/<module_name>/<module_name>.omod` to `keEMR-x.y.z/modules` - Do this for every exra module.
-- Copy `keEMR-x.y.z/configuration`, `keEMR-x.y.z/modules` and `keEMR-x.y.z/frontend` directories to the `oMRS_data_dir` directory.
-- Create a database named `openmrs` and import/restore it contents  from `keEMR-x.y.z/databases/openmrs.sql` SQL dump file.
-- Apply any database migration files that are in the `keEMR-x.y.z/migrations/install` directory to the `openmrs` (unless specified otherwise) database. 
-If non are available, skip this step.
-- Apply any database migration files that are in the `keEMR-x.y.z/extra_modules/<module_name>/migrations/install`  directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module.
+- Copy `kenyaEMR-x.y.z/configuration`, `kenyaEMR-x.y.z/modules` and `kenyaEMR-x.y.z/frontend` directories to the `oMRS_data_dir` directory.
+- Create a database named `openmrs` and import/restore it contents  from `kenyaEMR-x.y.z/databases/openmrs.sql` SQL dump file.
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/migrations/install` directory to the `openmrs` (unless specified otherwise) database. 
 If non are available, skip this step.
 - Create an openmrs [runtime properties file](https://wiki.openmrs.org/display/docs/Overriding+OpenMRS+Default+Runtime+Properties) and populate it with the appropriate settings for your installation.
 - Restart the target servlet container.
 - After a successful start of KenyaEMR;
-- Apply any database migration files that are in the `keEMR-x.y.z/migrations/post_install` directory to the `openmrs` (unless specified otherwise) database. 
-If non are available, skip this step.
-- Apply any database migration files that are in the `keEMR-x.y.z/<extra_modules>/<module_name>/migrations/post_install` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every module. 
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/migrations/post_install` directory to the `openmrs` (unless specified otherwise) database. 
 If non are available, skip this step.
     > **Note:** _You might be required to stop the target servlet container before running these migrations or perform some additional steps. If this is the case, it will be indicated on the release README._
 
 - That's it :thumbsup:, restart the servlet container (if not already started) and you should be good to go.
 
 ### Upgrade
 - Download the release archive from the [releases section](https://github.com/savannahghi/kenya-emr-releases/releases).
-- Unarchive the downloaded file into a temporary directory. We will refer to this directory as `keEMR-x.y.z`.
+- Unarchive the downloaded file into a temporary directory. We will refer to this directory as `kenyaEMR-x.y.z`.
 - Stop the target servlet container if running.
-- Replace the `openmrs.war` file in the webapps (or similar) directory of the servlet container with the one in the `keEMR-x.y.z/webapps` directory.
+- Replace the `openmrs.war` file in the webapps (or similar) directory of the servlet container with the one in the `kenyaEMR-x.y.z/webapps` directory.
 - Locate the [OpenMRS data directory](https://wiki.openmrs.org/display/docs/Application+Data+Directory) of the installation. We will refer to this directory as `oMRS_data_dir`.
 - Delete the following sub-directories from the `oMRS_data_dir` directory: `configuration`, `modules` and `frontend`.
-- Copy omods in `keEMR-x.y.z/extra_modules/<module_name>/<module_name>.omod` to `keEMR-x.y.z/modules` - Do this for every exra module.
-- Copy `keEMR-x.y.z/configuration`, `keEMR-x.y.z/modules`, `keEMR-x.y.z/extra_modules` and `keEMR-x.y.z/frontend` directories to the `oMRS_data_dir` directory.
-- Apply any database migration files that are in the `keEMR-x.y.z/migrations/upgrade` directory to the `openmrs` (unless specified otherwise) database. 
+- Copy `kenyaEMR-x.y.z/configuration`, `kenyaEMR-x.y.z/modules` and `kenyaEMR-x.y.z/frontend` directories to the `oMRS_data_dir` directory.
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/migrations/upgrade` directory to the `openmrs` (unless specified otherwise) database. 
 If non are available, skip this step.
-- Apply any database migration files that are in the `keEMR-x.y.z/<extra_modules>/<module_name>/migrations/upgrade` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module. 
+- Restart the target servlet container.
+- After a successful start of KenyaEMR;
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/migrations/post_upgrade` directory to the `openmrs` (unless specified otherwise) database. 
+If non are available, skip this step.
+    > **Note:** _You might be required to stop the target servlet container before running these migrations or perform some additional steps. If this is the case, it will be indicated on the release README._
+
+- That's it :thumbsup:, restart the servlet container (if not already started) and you should be good to go.
+
+
+## 2) Extra modules deployment
+
+These are modules that are not part of the standard kenyaEMR module deployment i.e they're not found packaged in the `modules` directory.  
+These modules are not required to run KenyaEMR, but we use them internally in our KenyaEMR deployments. You can safely ignore them.
+
+```
+
+KenyaEMR-v{x.y.z}.tar.xz
+└── kenya-emr-release-content - Release content root folder.
+    .
+    .
+    └── extra_modules - OpenMRS module files (omod) that are not part of official KenyaEMR release
+        ├── module_x - Directory containing extra module, typically named same as <module_name>
+        |    └── migrations - Database migration files. Follows the same hierarchy as shown in parent folder
+        |           ├── install - SQL migration files to run during installation.
+        |           |   └── *.sql (optional)
+        |           ├── post_install - SQL migration files to run after installation.
+        |           |   └── *.sql (optional)
+        |           ├── upgrade - SQL migration files to run during an upgrade.
+        |           |   └── *.sql (optional)
+        |           ├── post_upgrade - SQL migration files to run after an upgrade.
+        |           |   └── *.sql (optional)
+        |           └── module_x.omod - the actual omod file. Must be named as <module_name>.omod
+        └── module^n - Other extra modules will follow the same hierarchy as above.
+                └── migrations ...
+                     ├── install
+                     .      .......
+                     .         ......
+                     .            .....
+                     └── module^n.omod 
+
+```
+
+### Installation
+
+- Copy `kenyaEMR-x.y.z/extra_modules` directories to the `oMRS_data_dir` directory.
+- Copy omods in `kenyaEMR-x.y.z/extra_modules/<module_name>/<module_name>.omod` to `kenyaEMR-x.y.z/modules` - Do this for every exra module.
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/extra_modules/<module_name>/migrations/install`  directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module.
 If non are available, skip this step.
 - Restart the target servlet container.
 - After a successful start of KenyaEMR;
-- Apply any database migration files that are in the `keEMR-x.y.z/migrations/post_upgrade` directory to the `openmrs` (unless specified otherwise) database. 
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/<extra_modules>/<module_name>/migrations/post_install` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every module. 
 If non are available, skip this step.
-- Apply any database migration files that are in the `keEMR-x.y.z/<extra_modules>/<module_name>/migrations/post_upgrade` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module.
+    > **Note:** _You might be required to stop the target servlet container before running these migrations or perform some additional steps. If this is the case, it will be indicated on the release README._
+
+- That's it :thumbsup:, restart the servlet container (if not already started) and you should be good to go.
+
+### Upgrade
+
+- Copy `kenyaEMR-x.y.z/extra_modules` directories to the `oMRS_data_dir` directory.
+- Copy omods in `kenyaEMR-x.y.z/extra_modules/<module_name>/<module_name>.omod` to `kenyaEMR-x.y.z/modules` - Do this for every exra module.
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/<extra_modules>/<module_name>/migrations/upgrade` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module. 
+If non are available, skip this step.
+- Restart the target servlet container.
+- After a successful start of KenyaEMR;
+- Apply any database migration files that are in the `kenyaEMR-x.y.z/<extra_modules>/<module_name>/migrations/post_upgrade` directory to the `openmrs` (unless specified otherwise) database - Repeat this for every extra module.
 If non are available, skip this step.
     > **Note:** _You might be required to stop the target servlet container before running these migrations or perform some additional steps. If this is the case, it will be indicated on the release README._
 
+
 - That's it :thumbsup:, restart the servlet container (if not already started) and you should be good to go.