From 644dccf07c3f887748f3fa05c6034ef308d3a561 Mon Sep 17 00:00:00 2001 From: pld Date: Thu, 19 Sep 2024 21:23:03 -0400 Subject: [PATCH] expand server setup --- .../quickstart-guide/running-the-app.mdx | 2 +- .../quickstart-guide/server-setup.mdx | 290 +++++++++++++++++- 2 files changed, 283 insertions(+), 9 deletions(-) diff --git a/docs/engineering/quickstart-guide/running-the-app.mdx b/docs/engineering/quickstart-guide/running-the-app.mdx index 8d1cb2491b..7978e394ab 100644 --- a/docs/engineering/quickstart-guide/running-the-app.mdx +++ b/docs/engineering/quickstart-guide/running-the-app.mdx @@ -33,7 +33,7 @@ to help you build a FHIR Core app using this repository: ### Creating a custom app release -[TBC: So that it points to your custom URL endpoints] +Creating a custom app release is necessary if you want to change the server that your OpenSRP2 app connects with. However, if you have or were already provided an app pointing to the server that you plan to use you can skip this step. 1. Clone the FHIRCore Repository diff --git a/docs/engineering/quickstart-guide/server-setup.mdx b/docs/engineering/quickstart-guide/server-setup.mdx index 98b0521d5c..eca8ec287c 100644 --- a/docs/engineering/quickstart-guide/server-setup.mdx +++ b/docs/engineering/quickstart-guide/server-setup.mdx @@ -15,20 +15,294 @@ HAPI FHIR|v6.1.9|[Docker image](https://hub.docker.com/layers/onaio/fhir-gateway FHIR Web|v3.1.3|[Docker image](https://hub.docker.com/layers/opensrp/web/v3.1.3/images/sha256-48d0ec2aafb0ec2dc7c79dc0f3fbcb55b4802e04c4d836449c8fb46217287afe?context=explore)
[Github release](https://github.com/onaio/fhir-web/releases/tag/v3.1.3) Sentry|≥ v21|[Documentation](https://github.com/getsentry/self-hosted/tree/master?tab=readme-ov-file)|Optional and recommended application monitoring -## FHIR Store +## FHIR API and data store -[Example with HAPI FHIR] +This service is responsible for storing FHIR data and exposing an API that conforms to the FHIR specification. Some options includes + +- HAPI FHIR and a PostgreSQL database +- Google Cloud Healthcare API + +See the [compatability matrix](#compatability-matrix) for notes for the versions of HAPI FHIR and PostgreSQL that are know to work with OpenSRP2. + +If you are using Kubernetes, use this [helm chart](https://github.com/opensrp/helm-charts/tree/main/charts/hapi-fhir) to deploy into your cluster. + +### HAPI FHIR configuration + +Set the `Health Probe Endpoint` to `/`. + +Use the `JAVA_OPTS` environment variable to tune the Java heap size if the application requires more memory. + +#### With an identity and access managment service + +If you are using Keycloak as an identity and access management service set the `SPRING_APPLICATION_JSON` environment variables to + +```json +{ + "hapi": { + "fhir": { + "allow_cascading_deletes": true, + "allow_multiple_delete": true, + "cors": { + "allow_Credentials": true, + "allowed_origin": ["*"] + }, + "delete_expunge_enabled": true, + "expunge_enabled": true, + "fhir_version": "R4", + "search-coord-core-pool-size": 20, + "search-coord-max-pool-size": 100, + "search-coord-queue-capacity": 200, + "subscription": { + "resthook_enabled": true + }, + "tester": { + "global": { + "fhir_version": "R4", + "name": "Global Tester", + "refuse_to_fetch_third_party_urls": false, + "server_address": "https:///fhir" + }, + "home": { + "fhir_version": "R4", + "name": "Local Tester", + "refuse_to_fetch_third_party_urls": false, + "server_address": "https:///fhir", + "validation": { + "requests_enabled": true, + "responses_enabled": true + } + } + }, + "use_apache_address_strategy": true, + "use_apache_address_strategy_https": true, + "validation": { + "requests_enabled": false, + "responses_enabled": false + } + } + }, + "keycloak": { + "auth-server-url": "https:///auth/", + "credentials": { + "secret": "" + }, + "enabled": true, + "realm": "", + "resource": "fhir-core-client", + "ssl-required": "none" + }, + "sentry": { + "enabled": true, + "options": { + "dsn": "https://", + "environment": "production", + "release": "v6.1.9-SNAPSHOT", + "tags": "{\"release-name\":\"fhir-server-auth\",\"release-namespace\":\"opensrp\"}" + } + }, + "spring": { + "batch": { + "job": { + "enabled": false + } + }, + "datasource": { + "driverClassName": "org.postgresql.Driver", + "max-active": 15, + "password": "", + "url": "jdbc:postgresql://:5432/", + "username": "" + }, + "flyway": { + "baselineOnMigrate": true, + "check-location": false, + "enabled": false + }, + "jpa": { + "properties": { + "hibernate.dialect": "org.hibernate.dialect.PostgreSQLDialect", + "hibernate.format_sql": false, + "hibernate.hbm2ddl.auto": "update", + "hibernate.show_sql": false + } + }, + "main": { + "allow-bean-definition-overriding":true + } + } +} +``` + + +#### With no authentication + +:::warning +TO maintain proper privacy and security always use authentication by default. In testing or staging environments where you can guarantee there will be no information on real people it may be acceptible to disable authentication. +::: + +If you are not using authentication set the `SPRING_APPLICATION_JSON` environment variables to: + +```json +{ + "hapi": { + "fhir": { + "allow_cascading_deletes": true, + "allow_multiple_delete": true, + "cors": { + "allow_Credentials": true, + "allowed_origin": ["*"] + }, + "delete_expunge_enabled": true, + "expunge_enabled": true, + "fhir_version": "R4", + "search-coord-core-pool-size": 20, + "search-coord-max-pool-size": 100, + "search-coord-queue-capacity": 200, + "server_address":"http://:8080/fhir", + "subscription": { + "resthook_enabled": true + }, + "tester": { + "home": { + "fhir_version": "R4", + "name": "Local Tester", + "refuse_to_fetch_third_party_urls": false, + "server_address": "http://localhost:8080/fhir", + "validation": { + "requests_enabled": true, + "responses_enabled": true + } + } + }, + "use_apache_address_strategy": false, + "use_apache_address_strategy_https": false, + "validation": { + "requests_enabled": false, + "responses_enabled": false + } + } + }, + "keycloak": { + "enabled":false + }, + "sentry": { + "enabled": true, + "options": { + "dsn": "https://", + "environment": "testing", + "release": "v6.1.9-SNAPSHOT", + "tags": "{\"release-name\":\"fhir-server-auth\",\"release-namespace\":\"opensrp\"}" + } + }, + "spring": { + "batch": { + "job": { + "enabled": false + } + }, + "datasource": { + "driverClassName": "org.postgresql.Driver", + "max-active": 15, + "password": "", + "url": "jdbc:postgresql://:5432/", + "username": "" + }, + "flyway": { + "baselineOnMigrate": true, + "check-location": false, + "enabled": false + }, + "jpa": { + "properties": { + "hibernate.dialect": "org.hibernate.dialect.PostgreSQLDialect", + "hibernate.format_sql": false, + "hibernate.hbm2ddl.auto": "update", + "hibernate.show_sql": false + } + }, + "main": { + "allow-bean-definition-overriding":true + } + } +} +``` ## Identity and Access Management (IAM) -[Example with Keycloak] +If deploying Keycloak as your IAM service on Kubernetes you can use the following `values.yml` file: -## FHIR Information Gateway +```yaml +--- +replicas: 2 -## Optional extensions +image: + repository: quay.io/keycloak/keycloak + tag: "22.0.5" + digest: "" + pullPolicy: IfNotPresent -### Admin dashboard +ingress: + enabled: true + annotations: + ... + +serviceMonitor: + enabled: true + +metrics: + enabled: true + +health: + enabled: true + +resources: + requests: + cpu: "500m" + memory: "1024Mi" + limits: + memory: "2048Mi" + +database: + vendor: postgres + hostname: "" + port: 5432 + database: "" + username: + password: + +command: + - "/opt/keycloak/bin/kc.sh" + - "--verbose" + - "start" + - "--http-enabled=true" + - "--http-port=8080" + - "--hostname-strict=false" + - "--hostname-strict-https=false" + - "--spi-events-listener-jboss-logging-success-level=info" + - "--spi-events-listener-jboss-logging-error-level=warn" -### Data warehouse +extraEnv: | + - name: KEYCLOAK_ADMIN + value: + - name: KEYCLOAK_ADMIN_PASSWORD + value: + - name: JAVA_OPTS_APPEND + value: >- + -XX:+UseContainerSupport + -XX:MaxRAMPercentage=50.0 + -Djava.awt.headless=true + -Djgroups.dns.query={{ include "keycloak.fullname" . }}-headless +``` + +## Recommended extensions + +### Monitoring + +Once the services have been deployed it will be necessary to monitor the deployed applications. Sentry is integrated into the OpenSRP2 FHIR Android app, FHIR web, and HAPI server to aid in application monitoring and logging. + +Apart from application monitoring one has to monitor the server resources and proxy logs. [Graylog](https://graylog.org/), [fluentbit](https://fluentbit.io/), and [Prometheus](https://prometheus.io/) are some of the tools that can help with this. It is recommended to configure alerting on these tools to help notify when a threshold is reached and a service is potentially inoperable. + + +### Admin dashboard -### Analytics dashboard +If deploying FHIR web as your admin dashboard on Kubernetes you can use this [helm chart](https://github.com/opensrp/helm-charts/tree/main/charts/opensrp-web).