Update Documentation 📝 (#3164)

* Update Documentation 📝 * move to backend --------- Co-authored-by: pld <[email protected]>
opensrp · Mar 21, 2024 · 22fd831 · 22fd831
1 parent e4565a9
commit 22fd831
Show file tree

Hide file tree

Showing 5 changed files with 51 additions and 13 deletions.
diff --git a/docs/engineering/android-app/automated-releases.mdx b/docs/engineering/android-app/automated-releases.mdx
@@ -103,6 +103,6 @@ Click on the *Run Workflow* button. This will trigger the action to run.
 After the action run is complete click on the last workflow run link.
 ![](/img/manual-workflow-run-link.png)
 
-Scroll to the bottom to find the generated artifact download link.
+Scroll to the bottom to find the generated artifact download link. Click to download.
 ![](/img/manual-workflow-release-artifact-link.png)
 
diff --git a/docs/engineering/android-app/developer-setup/publishing-fhir-sdk-artifacts.mdx b/docs/engineering/android-app/developer-setup/publishing-fhir-sdk-artifacts.mdx
@@ -12,6 +12,7 @@ At the moment, we have the following FHIR SDK artifacts that need to be released
 - Android FHIR Structured Data Capture Library
 - Android FHIR Workflow Library
 - Android FHIR Structured Data Capture - Barcode Extensions (contrib)
+- Android FHIR Structured Data Capture - Location Widget Extensions (contrib)
 
 Sometimes one wants to test the changes on the repo e.g. on the `master` branch without doing a remote release to _Sonatype_ during development. It is possible to do this locally.
 
@@ -53,15 +54,15 @@ Building FHIR Core should now import the new artifact version. MavenLocal is alr
 
   #### Processes
 
-  1. On OpenSRP's Github fork of the Android FHIR SDK (Assuming there are new changes) click on _Sync fork_
+  1. On [OpenSRP's Github fork of the Android FHIR SDK](https://github.com/opensrp/android-fhir) (Assuming there are new changes) click on _Sync fork_
   2. _Check out_ to `master` branch locally and _pull_ the latest changes
   3. _Checkout_ to `master-release` branch and _merge_ in `master` changes
   4. _Update the versions_ of the various modules you want to publish in the `buildSrc/src/main/kotlin/Releases.kt` file
   5. Update the [versions of the dependencies here](https://github.com/google/android-fhir/blob/master/buildSrc/src/main/kotlin/Dependencies.kt#L250-L252) used internally by the SDK
   6. _Make a commit_ with the updated versions and _add a commit message_ in the format shown in the [Commits section below](#commits)
   7. Push the commit to the `master-release` branch for tracking
   8. Now that the `master-release` branch has all the latest updates from parent `master`, _Check out_ to a new branch on your local with today's date in the dot separated double digit format **DD-MM-YYYY** and prefixe with `release-` e.g. `release-20.10.2023`
-  9. Merge in any other unmerged PR branches mentioned in the previous commit message and have not been merged to `master` yet
+  9. Merge in any other unmerged PR branches mentioned in the previous commit message and have not been merged to `master` yet. Ensure they branches have been updated with the latest master/main branch.
   10. _Publish_ the specific modules that you wanted. See the [Publishing section below](#publishing)
   11. After a successful publish to Maven push your release branch above for versioning.
 
@@ -75,8 +76,8 @@ Building FHIR Core should now import the new artifact version. MavenLocal is alr
 
   ```
    SDK Release: Engine, SDC, Workflow, Contrib:Barcode, Common, Knowledger
-   - With unmerged PR #1344 branch
-   - With unmerged PR #1542 branch
+   - With unmerged PR #1344
+   - With unmerged PR #1542
   ```
 See related [sample commit here](https://github.com/google/android-fhir/commit/10e46a0eac5f41b68b5bb1caa87069b83d36c6b1)
 
@@ -100,6 +101,12 @@ See related [sample commit here](https://github.com/google/android-fhir/commit/1
   ### Publishing
 
   Once all the above is in place you just need to run the command: <br/>
-`./gradlew :datacapture:publishReleasePublicationToSonatypeRepository --stacktrace`. All the other modules follow a similar format, you only need to change the module you are targeting, e.g. to publish _engine_ use the command: <br/> `./gradlew :engine:publishReleasePublicationToSonatypeRepository --stacktrace`
+```shell
+./gradlew :datacapture:publishReleasePublicationToSonatypeRepository --stacktrace
+```
+All the other modules follow a similar format, you only need to change the module you are targeting, e.g. to publish _engine_ use the command: <br/> 
+```shell
+./gradlew :engine:publishReleasePublicationToSonatypeRepository --stacktrace
+```
 <br/><br/>
-Your artifact should now be available under the corresponding artifact group under your org. on Sonatype <br/> `https://oss.sonatype.org/content/repositories/snapshots/org/smartregister/data-capture/`
+Your artifact should now be available under the corresponding artifact group under your org. on Sonatype <br/> e.g. see [OpenSRP Standard Data Capture Artifacts](https://oss.sonatype.org/content/repositories/snapshots/org/smartregister/data-capture/)
diff --git a/docs/engineering/backend/architecture.mdx b/docs/engineering/backend/architecture.mdx
@@ -28,9 +28,9 @@ For on premise implementations the [FHIR Data Pipes](https://github.com/google/f
 
 OpenSRP connects to a third party identity and access management (IAM) system to authenticate and authorize users of the system.
 
-#### FHIR Access Proxy
+#### FHIR Info Gateway
 
-The [FHIR Access Proxy](https://github.com/google/fhir-access-proxy) is an open source endpoint agnostic interface between an IAM and a health store.
+The [FHIR Info Gateway](https://github.com/google/fhir-access-proxy) is an open source endpoint agnostic interface between an IAM and a health store.
 
 #### Keycloak
 
@@ -40,6 +40,6 @@ The [FHIR Access Proxy](https://github.com/google/fhir-access-proxy) is an open
 
 This allows the user to view data in a health data store and perform common editing and management tasks on this data.
 
-#### fhir-web
+#### FHIR-Web
 
 The source available [fhir-web](https://github.com/opensrp/web) web application allows you to view FHIR resources, create new FHIR resources, and manage user access to FHIR systems through FHIR Practitioner resources associated with an IAM.
diff --git a/docs/engineering/backend/production.mdx b/docs/engineering/backend/production.mdx
@@ -0,0 +1,24 @@
+# Production setup
+
+This page provides recommendations when setting up a production deployment. 
+
+### Keycloak Oauth2 clients
+
+We use [Keycloak](https://www.keycloak.org/) as our IAM server that stores users, groups, and the access roles of those groups. Before starting the set up of the Keycloak Oauth clients ensure the `Service Account` Role is **disabled**.  
+_Separate_ OAuth clients should be configured for the ETL Pipes/Analytics and the FHIR Web systems.
+
+
+#### Android client
+Enable **Direct Access Grant only** - This client should be configured as a `Public` client. To fetch a token you will not need the client secret. This will use the `Resource Credentials/Password` Grant type. 
+
+:::danger
+
+Do not store any sensitive data like _password credentials_ or _secrets_ in your production APK e.g. in the `local.properties` file.
+
+::::
+
+#### FHIR Web client
+Enable **Client Authentication** and enable **Standard flow**. _Implicit flow should only be used for local dev testing - it can be configured for stage and maybe preview but NOT production._. This will use the  
+
+#### Data pipelines/Analytics client
+Enable **Client Authentication** and enable **Service Account Roles**. This will use the `Client Credentials` grant type.
diff --git a/docs/engineering/backend/readme.mdx b/docs/engineering/backend/readme.mdx
@@ -6,12 +6,19 @@ sidebar_label: Backend
 
 ## Backend application setup
 
-The backend requires at a minimum two pieces of software, with an optional third:
+The backend requires these pieces of software, with an optional fourth:
 
-1. a FHIR Store, e.g HAPI FHIR
-2. the [FHIR Information Gateway](https://github.com/onaio/fhir-gateway-plugin) with [OpenSRP plugins](https://hub.docker.com/r/onaio/fhir-gateway-plugin/tags)
+1. FHIR Store, e.g HAPI FHIR - [How to set up HAPI FHIR](https://github.com/hapifhir/hapi-fhir-jpaserver-starter)
+2. [FHIR Information Gateway](https://github.com/onaio/fhir-gateway-plugin) with [OpenSRP plugins](https://hub.docker.com/r/onaio/fhir-gateway-plugin/tags) - [How to set up OpenSRP FHIR Gateway](https://github.com/onaio/fhir-gateway-extension)
+3. Identity and Access Management server with Oauth2 support e.g. Keycloak - [How to set up Keycloak](https://github.com/keycloak/keycloak)
 3. [Optional] the [fhir-web](https://github.com/onaio/fhir-web) admin dashboard.
 
+:::info
+
+For deployment to production, see some of your recommendations on the set up. [Production configuration](https://docs.opensrp.io/engineering/production).
+
+:::
+
 ## User management
 
 You can manage users manually via the APIs and/or user interfaces for keycloak and your FHIR API, or via the fhir-web user interface. See [Keycloak](backend/keycloak) for details.