Merge pull request #50 from bcgsc/feature/keycloak-redirect-instructions

Add troubleshooting section

docs/faq.md → docs/help/faq.md

@@ -1,4 +1,4 @@
-# FAQ
+# General FAQ
 
 ## How does Variant Annotation Work?
 
@@ -12,12 +12,12 @@ consists of the following steps
 - Follows inferences (ex. g. -> p.)
 - Pull statements for these variant records
 
-[^1]: Only applicable to postional variants, these steps are skipped when matching category variants.
+[^1]: Only applicable to positional variants, these steps are skipped when matching category variants.
 
-This allows an input like `KRAS:p.G12D` to match to all eqiuvalent forms of this variant. For example,
+This allows an input like `KRAS:p.G12D` to match to all equivalent forms of this variant. For example,
 in the demo database it would result in the following matches
 
-![kras matching](./images/kras_variant_matching.png)
+![kras matching](../images/kras_variant_matching.png)
 
 ## How do I cite PORI?
 
@@ -48,7 +48,7 @@ We welcome and encourage community contributions! If you have a feature request,
 If you are a developer and would like to directly add and work on features, please submit a ticket
 for any new features and indicate that you would like to complete it or comment on an existing ticket.
 Following discussion with the main developers you should fork the repository and then submit a pull request
-from your forked version to the main repository. Please see the developer contributing guidelines [here](./developer_reference/contributing.md)
+from your forked version to the main repository. Please see the developer contributing guidelines [here](../developer_reference/contributing.md)
 
 ## How Can I Try This Out?
 

docs/help/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+The following page contains questions related to set up, install, and management of the PORI system.
+
+## Keycloak
+
+### Invalid parameter: redirect_uri
+
+Valid redirect URIs are configured/set via the keycloak admin console. If you have set up the platform following the demo/dev instructions then you should already have the keycloak administrative console available over http. Go to http://localhost:8888/auth in your web browser and you should see something that looks like this. The user and password for this should be admin/admin for the [dev setup](https://github.com/bcgsc/pori/blob/master/docker-compose.dev.yml#L10).
+
+![auth admin page](../images/troubleshooting-keycloak-redirect-uri-1.png)
+
+Go the "Clients" in the left-hand side bar
+
+![go to client page](../images/troubleshooting-keycloak-redirect-uri-2.png)
+
+Click on the "GraphKB" client
+
+![pick client](../images/troubleshooting-keycloak-redirect-uri-3.png)
+
+Scroll near the bottom on that page and you will find the "valid redirect URLs" where you need to add your host
+
+![change valid redirects](../images/troubleshooting-keycloak-redirect-uri-4.png)

mkdocs.yml

@@ -50,8 +50,8 @@ nav:
   - demo.md
   - install.md
   - repos.md
-  - faq.md
   - ... | graphkb/**
   - ... | ipr/**
   - ... | variant_notation/**
+  - ... | help/**
   - ... | developer_reference/**