From 22fd8311a0ceffe1cb1eb20064f6679c80aa317e Mon Sep 17 00:00:00 2001 From: Martin Ndegwa Date: Thu, 21 Mar 2024 21:34:30 +0300 Subject: [PATCH] =?UTF-8?q?Update=20Documentation=20=F0=9F=93=9D=20(#3164)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update Documentation 📝 * move to backend --------- Co-authored-by: pld --- .../android-app/automated-releases.mdx | 2 +- .../publishing-fhir-sdk-artifacts.mdx | 19 ++++++++++----- docs/engineering/backend/architecture.mdx | 6 ++--- docs/engineering/backend/production.mdx | 24 +++++++++++++++++++ docs/engineering/backend/readme.mdx | 13 +++++++--- 5 files changed, 51 insertions(+), 13 deletions(-) create mode 100644 docs/engineering/backend/production.mdx diff --git a/docs/engineering/android-app/automated-releases.mdx b/docs/engineering/android-app/automated-releases.mdx index b0561a9333..947cbd62a0 100644 --- 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 index cdd46f6e84..a3a8925512 100644 --- 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,7 +54,7 @@ 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 @@ -61,7 +62,7 @@ Building FHIR Core should now import the new artifact version. MavenLocal is alr 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:
-`./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:
`./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:
+```shell +./gradlew :engine:publishReleasePublicationToSonatypeRepository --stacktrace +```

-Your artifact should now be available under the corresponding artifact group under your org. on Sonatype
`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
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 index e57b248388..03ba97ce57 100644 --- 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 new file mode 100644 index 0000000000..004b220770 --- /dev/null +++ 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 index db45cff057..1abea3360a 100644 --- 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.