fixes to docker and access-checker tutorial, contribute, etc.

doc/docs/contribute.md

@@ -1,21 +1,31 @@
 # How to Contribute
 
-We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
 
 ## Contributor License Agreement
 
-Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to <https://cla.developers.google.com/> to see your current agreements on file or to sign a new one.
+Contributions to this project must be accompanied by a Contributor License
+Agreement (CLA). You (or your employer) retain the copyright to your
+contribution; this simply gives us permission to use and redistribute your
+contributions as part of the project. Head over
+to <https://cla.developers.google.com/> to see your current agreements on file
+or to sign a new one.
 
-You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.
+You generally only need to submit a CLA once, so if you've already submitted
+one (even if it was for a different project), you probably don't need to do it
+again.
 
 ## Code reviews
 
-All submissions by non-project members, require review. We use GitHub pull requests for this purpose. 
+All code changes require review. We use GitHub pull-requests for this purpose.
 
-* Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. 
+* Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/)
+  for more information on using pull requests.
 
 * We use GitHub for issue tracking.
 
 ## Community Guidelines
 
-This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
+This project
+follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).

doc/docs/release_process.md

@@ -1,31 +1,44 @@
 # Semantic versioning
 
-Versioning across all Open Health Stack components is based on the major.minor.patch scheme and respects Semantic Versioning.
+FHIR Info Gateway artifacts are released on
+[Maven](https://central.sonatype.com/namespace/com.google.fhir.gateway). A
+docker image is also published on
+[GCP Artifact Registry](https://console.cloud.google.com/artifacts/docker/fhir-proxy-build/us/stable/fhir-gateway?project=fhir-proxy-build).
+
+Versioning across all Open Health Stack components is based on the
+major.minor.patch scheme and respects Semantic Versioning.
 
 Respecting Semantic Versioning is important for multiple reasons:
 
-*   It guarantees simple minor version upgrades, as long as you only use the public APIs
-*   A new major version is an opportunity to thoroughly document breaking changes
-*   A new major/minor version is an opportunity to communicate new features through a blog post
+* It guarantees simple minor version upgrades, as long as you only use the
+  public APIs.
+* A new major version is an opportunity to thoroughly document breaking changes.
+* A new major/minor version is an opportunity to communicate new features
+  through a blog post.
 
 ## Major versions
+
 The major version number is incremented on every breaking change.
 
 Whenever a new major version is released, we publish:
 
-*   a blog post with feature highlights, major bug fixes, breaking changes, and upgrade instructions.
-*   an exhaustive changelog entry via the release notes
+* a blog post with feature highlights, major bug fixes, breaking changes, and
+  upgrade instructions.
+* an exhaustive changelog entry via the release notes
 
 ## Minor versions
-The minor version number is incremented on every significant retro-compatible change.
+
+The minor version number is incremented on every significant retro-compatible
+change.
 
 Whenever a new minor version is released, we publish:
 
-*   an exhaustive changelog entry via the release notes
+* an exhaustive changelog entry via the release notes.
 
 ## Patch versions
+
 The patch version number is incremented on bugfixes releases.
 
 Whenever a new patch version is released, we publish:
 
-*   an exhaustive changelog entry
+* an exhaustive changelog entry.

doc/docs/support.md

@@ -1,33 +1,46 @@
 # Support
 
-On this page we've listed some ways you can get technical support and Open Health Stack communities and forums that you can be a part of.
+On this page we've listed some ways you can get technical support along with
+Open Health Stack communities and forums that you can be a part of.
 
-Before participating please read our [code of conduct](https://opensource.google/conduct) that we expect all community members to adhere too.
+Before participating please read
+our [code of conduct](https://opensource.google/conduct) that we expect all
+community members to adhere too.
 
 ## Developer calls
-There are weekly Open Health Stack developer calls that you are welcome to join. 
 
-* Calls are on Thursdays and *Alternate* between Android FHIR SDK and OHS server side (FHIR Data Pipes and Info Gateway)
-* See the schedule below for more details
-* To be added to the calls, please please email: hello-ohs[at]google.com
+There are weekly Open Health Stack developer calls that you are welcome to join.
+
+* Calls are on Thursdays and **alternate** between Android FHIR SDK and OHS
+  server side components (FHIR Data Pipes and Info Gateway).
+* See the schedule below for more details.
+* To be added to the calls, please email: `hello-ohs[at]google.com`.
 
 **Developer call schedule**
 
 | OHS Developers Call | GMT | East Africa | India |
-| :------------ | :-: | :---------: | :---: | 
+| :------------ | :-: | :---------: | :---: |
 | Android FHIR SDK | 10:00 UK | 12:00 Nairobi | 14:30 Delhi |
 | Analytics and Info Gateway | 13:00 UK | 15:00 Nairobi | 17:30 Delhi |
 
 ## Discussion forums
 
-We are in the process of setting up a dedicated discussion forum for Open Health Stack. In the meantime, you can reach out to hello-ohs[at]google.com
+We are in the process of setting up a dedicated discussion forum for Open Health
+Stack. In the meantime, you can reach out to `hello-ohs[at]google.com`.
 
 ## Stack Overflow
-Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the existing questions tagged with open-health-stack or fhir-data-pipes or ask your own!
 
-## Bugs or Feature reqeusts
-Before submitting a bug or filing a feature reqeust, please review the open issues on our [github repository](https://github.com/google/fhir-data-pipes/issues).
+Stack Overflow is a popular forum to ask code-level questions or if you're stuck
+with a specific error. It would be nice to tag your question with
+`open-health-stack`!
+
+## Bugs or Feature requests
+
+Before submitting a bug or filing a feature reqeust, please review the open
+issues on
+our [github repository](https://github.com/google/fhir-data-pipes/issues).
 
-If your issue is there, please add a comment. Otherwise, create a new issue to file a bug or submit a new feature request.
+If your issue is there, please add a comment. Otherwise, create a new issue to
+file a bug or submit a new feature request.
 
-Please review the [contributing section](contributing.md).
+Please review the [contributing section](contribute.md).

doc/docs/tutorial_docker.md

@@ -2,43 +2,39 @@
 
 In this guide, you will learn how to run FHIR Info Gateway in a Docker
 image, and see it work in concert with a sample Keycloak and HAPI FHIR server
-running on your local machine. 
-
-**Requirements:** 
-
-- This guide requires Linux
-- Assumes you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/) installed.
+running on your local machine. We assume that
+[Docker](https://docs.docker.com/get-docker/) and
+[Docker Compose](https://docs.docker.com/compose/) are installed. The sample
+commands are shown on a Linux/shell environment and may need to be adjusted for
+your environment.
 
 !!! tip "Important"
 
     The setup used in this guide **should not be used in a production environment**. It is designed to get things up and running quickly for demonstration or testing purposes only. The FHIR Information Gateway Docker image might be used in a production environment if deployed appropriately, however the example access-checker plugins may not satisfy real-world use cases.
 
 ## Start the Docker images
 
-1.  Clone the [FHIR Info Gateway repo from GitHub](https://github.com/google/fhir-gateway).
-2.  Open a terminal window and `cd` to the directory where you cloned the FHIR Info Gateway repo.
-3.  Bring up the sample Keycloak service using `docker-compose`. 
-
-    ```shell
-    docker-compose -f docker/keycloak/config-compose.yaml up
-    ```
-
-    This runs an instance of [Keycloak extensions for
-    FHIR](https://github.com/Alvearie/keycloak-extensions-for-fhir) preloaded
-    with a test configuration. It is accessible at http://localhost:9080.
+1. Clone
+   the [FHIR Info Gateway repo from GitHub](https://github.com/google/fhir-gateway).
+2. Open a terminal window and `cd` to the directory where you cloned the repo.
+3. Bring up the sample Keycloak service using `docker compose`.
+   ```shell
+   docker compose -f docker/keycloak/config-compose.yaml up
+   ```
+   This runs an instance of [Keycloak](https://www.keycloak.org/) with
+   [SoF extension](https://github.com/Alvearie/keycloak-extensions-for-fhir),
+   preloaded with a test configuration. It is accessible at
+   `http://localhost:9080`.
 
 4.  Run the sample HAPI FHIR server Docker image.
-
     ```shell
     docker run -p 8099:8080 us-docker.pkg.dev/fhir-proxy-build/stable/hapi-synthea:latest
     ```
-
     The server is preloaded with synthetic patient data and a FHIR
     `List/patient-list-example` resource.
 
 5.  Run the FHIR Information Gateway Docker image with the `list` access
     checker.
-
     ```shell
     docker run \
       -e TOKEN_ISSUER=http://localhost:9080/auth/realms/test \
@@ -50,34 +46,33 @@ running on your local machine.
       us-docker.pkg.dev/fhir-proxy-build/stable/fhir-gateway:latest
     ```
 
-    Several environment variables are used to configure FHIR Information
-    Gateway:
-
-*   _TOKEN_ISSUER_: The URL of the OpenID Issuer. For Keycloak this is typically
-    `http://{keycloak-host}:{keycloak-port}/auth/realms/{realm-name}`.
-*   _PROXY_TO_: The [Service Base URL](https://build.fhir.org/http.html#root) of
-    the FHIR server that FHIR Access Proxy communicates with.
-*   _BACKEND_TYPE_: One of `HAPI` for a HAPI FHIR Server or `GCP` for a Cloud
-    Healthcare API FHIR store.
-*   _RUN_MODE_: One of `PROD` or `DEV`. DEV removes validation of the issuer URL,
-    which is useful when using the docker image with an Android emulator as the
-    emulator runs on its own virtual network and sees a different address than
-    the host.
-*   _ACCESS_CHECKER_:  The access-checker plugin to use. The Docker image includes
-    the [`list`](https://github.com/google/fhir-gateway/blob/main/plugins/src/main/java/com/google/fhir/gateway/plugin/ListAccessChecker.java)
-    and [`patient`](https://github.com/google/fhir-gateway/blob/main/plugins/src/main/java/com/google/fhir/gateway/plugin/PatientAccessChecker.java)
-    example access-checkers.
+Several environment variables are used to configure FHIR Information Gateway:
+
+* `TOKEN_ISSUER`: The URL of the token issuer. For Keycloak this is typically
+  `http://{keycloak-host}:{keycloak-port}/auth/realms/{realm-name}`.
+* `PROXY_TO`: The [Service Base URL](https://build.fhir.org/http.html#root) of
+  the FHIR server that FHIR Access Proxy communicates with.
+* `BACKEND_TYPE`: One of `HAPI` for a HAPI FHIR Server or `GCP` for a Cloud
+  Healthcare FHIR-store.
+* `RUN_MODE`: One of `PROD` or `DEV`. DEV removes validation of the issuer URL,
+  which is useful when using the docker image with an Android emulator as the
+  emulator runs on its own virtual network and sees a different address than
+  the host.
+* `ACCESS_CHECKER`:  The access-checker plugin to use. The Docker image includes
+  the [`list`](https://github.com/google/fhir-gateway/blob/main/plugins/src/main/java/com/google/fhir/gateway/plugin/ListAccessChecker.java)
+  and [`patient`](https://github.com/google/fhir-gateway/blob/main/plugins/src/main/java/com/google/fhir/gateway/plugin/PatientAccessChecker.java)
+  example access-checkers.
 
 !!! tip "GCP Note"
 
     If the FHIR server is GCP FHIR-store and the gateway is not run on a VM with proper service account (e.g., running on a localhost), you need to pass GCP credentials to it, for example by mapping the `.config/gcloud` volume (i.e., add `-v ~/.config/gcloud:/root/.config/gcloud` to the above command).
 
 ## Examine the sample Keycloak configuration
 
-In this section you will review the Keycloak settings relevant to use FHIR
+In this section you will review the Keycloak settings relevant to the FHIR
 Information Gateway with the sample `list` access checker plugin.
 
-1.  Open a web browser and navigate to http://localhost:9080/auth/admin/.
+1.  Open a web browser and navigate to `http://localhost:9080/auth/admin/`.
 2.  Login using user `admin` and password `adminpass`.
 3.  Select the `test` realm.
 4.  From the left menu, find the **Manage** section and click **Users**. Click
@@ -91,7 +86,7 @@ Information Gateway with the sample `list` access checker plugin.
     **Clients > my-fhir-client > Mappers > list-mapper**.
 6.  `patient-list-example` is the ID of a FHIR List resource which lists all the
     Patient resources the user can access. Open
-    http://localhost:8099/fhir/List/patient-list-example to see the list
+    `http://localhost:8099/fhir/List/patient-list-example` to see the list
     referencing two Patients: 
 
     ```json
@@ -129,7 +124,7 @@ Information Gateway with the sample `list` access checker plugin.
 
     You will need to rerun this command when the access token expires after 5
     minutes. In a real application, implement your Identity Provider's
-    authentication flow.
+    authentication flow, including refresh tokens.
 
 2.  Send a request to FHIR Information Gateway using the access token.
 

doc/docs/tutorial_first_access_checker.md

@@ -1,13 +1,26 @@
 # Create an access checker plugin
+
 In this guide you will create your own access checker plugin.
 
-## Implement the AccessCheckerFactory interface
-To create your own access checker plugin, create an implementation of the [`AccessCheckerFactory` interface](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessCheckerFactory.java) annotated with a `@Named(value = "name")` annotation defining the name of the plugin. 
+## Implement the `AccessCheckerFactory` interface
+
+To create your own access checker plugin, create an implementation of
+the [`AccessCheckerFactory` interface](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessCheckerFactory.java)
+annotated with a `@Named(value = "name")` annotation defining the name of the
+plugin.
 
-The most important parts are to implement a custom [`AccessChecker`](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessChecker.java) to be returned by the factory and its `checkAccess` function which specifies if access is granted or not by returning an [`AccessDecision`](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessDecision.java).
+The most important parts are to implement a
+custom [`AccessChecker`](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessChecker.java)
+to be returned by the factory and its `checkAccess` function which specifies if
+access is granted or not by returning
+an [`AccessDecision`](https://github.com/google/fhir-gateway/blob/main/server/src/main/java/com/google/fhir/gateway/interfaces/AccessDecision.java).
 
 ## Create a new class
-The simplest way to create your own access checker is to make a new class file in the `plugins/src/main/java/com/google/fhir/gateway/plugin` directory, next to the existing sample plugins. The following code can be used as a starting template for a minimal access checker.
+
+The simplest way to create your own access checker is to make a new class file
+in the `plugins/src/main/java/com/google/fhir/gateway/plugin` directory, next to
+the existing sample plugins. The following code can be used as a starting
+template for a minimal access checker:
 
 ```java
 package com.google.fhir.gateway.plugin;
@@ -32,7 +45,8 @@ public class MyAccessChecker implements AccessChecker {
   private final String claim;
   private final PatientFinder patientFinder;
 
-  // We're not using any of the parameters here, but real access checkers would likely use some/all.
+  // We're not using any of the parameters here, but real access checkers
+  // would likely use some/all.
   private MyAccessChecker(
       HttpFhirClient httpFhirClient,
       String claim,
@@ -50,7 +64,8 @@ public class MyAccessChecker implements AccessChecker {
     return NoOpAccessDecision.accessGranted();
   }
 
-  // The factory must be thread-safe.
+  // The factory must be thread-safe but the AccessChecker instances it returns
+  // do not need to be thread-safe.
   @Named(value = "sample")
   public static class Factory implements AccessCheckerFactory {
 
@@ -74,8 +89,11 @@ public class MyAccessChecker implements AccessChecker {
 
 ```
 
-## Rebuild mvn package to include the plugin
-Once you're done implementing your access checker plugin, rebuild using `mvn package` from the root of the project to include the plugin, set the access checker using e.g. `export ACCESS_CHECKER=sample`
+## Rebuild to include the plugin
+Once you're done implementing your access checker plugin, rebuild using
+`mvn package` from the root of the project to include the plugin, set the
+access-checker using e.g. `export ACCESS_CHECKER=sample`
 
 ## Run the gateway
-Run the gateway using e.g. `java -jar exec/target/exec-0.1.0.jar --server.port=8080`.
+Run the gateway using e.g.
+`java -jar exec/target/exec-0.1.0.jar --server.port=8080`.