config-home.yaml description updated

sensein · Jul 29, 2024 · 9ed823e · 9ed823e
1 parent 3bb2e4f
commit 9ed823e
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 39 deletions.
diff --git a/docs/brainkbui.md b/docs/brainkbui.md
@@ -1,4 +1,5 @@
 # User Interface Overview
+The currently deployment can be accessed at [http://3.149.235.227:3000/](http://3.149.235.227:3000/).
 
 ```{figure} home.png
 :name: brainkb_uihome_figure

diff --git a/docs/deployment_userinterface.md b/docs/deployment_userinterface.md
@@ -4,14 +4,17 @@ This section provides information regarding the deployment of the BrainKB UI, bo
 ## System Requirements
 - The BrainKB UI is based on NextJS; we need to install the Node.js. When writing this document, the minimum version is **Node.js 18.17 or later**. For more (or latest) information, please check NextJS website.
 
-	- [https://nextjs.org/docs/getting-started/installation](https://nextjs.org/docs/getting-started/installation)
+	- NextJS: [https://nextjs.org/docs/getting-started/installation](https://nextjs.org/docs/getting-started/installation)
 	- **<span style="color: red;">Note:</span>** Manual installation of latest version of NextJS.
 
 		```
 		npm install next@latest react@latest react-dom@latest
 		```
 		If you get issue with depenency, add `--legacy-peer-deps` options.
-	- Installation of the dependencies
+	- Installation of the dependencies.
+		```
+		npm install 
+		```
 
 - Once all the NextJS requirements has been met or covered, next step is to configure the OAuth. In our case we use Google and GitHub. Therefore, you would need to obtain the OAuth client ID and secret and update the ```.env.local``` file (shown below). Additionally, you also need to provide the secret for [NextAuth](https://next-auth.js.org/), a library that we use authentication. The ```NEXTAUTH_URL``` for development is ```http://localhost:3000```. Similarly, the GitHub secret and client ID can be obtained from GitHub at [https://github.com/settings/tokens](https://github.com/settings/tokens) and Google at [https://console.cloud.google.com/](https://console.cloud.google.com/).
 
@@ -36,22 +39,28 @@ This section provides information regarding the deployment of the BrainKB UI, bo
 	:name: google_oauth_setup
 	Google OAuth setup.
 	```
-- The next step is to configure the `config-home.yaml` and `config-knowledgebases.yaml` inside `components` directory. {ref}`content:references:configurationfilesui` section provides the `config-home.yaml` and `config-knowledgebases.yaml` configuration file for the BrainKB UI. The `config-home.yaml` is use to configure the home (or landing) page and `config-knowledgebases.yaml` is use to configure the `knowledge base` page. {numref}`brainkbdocs-headerconfig` and {numref}`brainkbdocs-statistics_structured_box` 
+- The next step is to configure the `config-home.yaml` and `config-knowledgebases.yaml` inside `components` directory. The `config-home.yaml` is use to configure the home (or landing) page and `config-knowledgebases.yaml` is use to configure the `knowledge base` page. {numref}`brainkbdocs-headerconfig` and {numref}`brainkbdocs-statistics_structured_box` show the configuration of the BrainKB UI landing page header using the `config-home.yaml` file. Similarly, {numref}`brainkbdocs-knowledgebasepage` shows the configuration of the `knowledge base` page using `config-knowledgebases.yaml` and the mappings of the configuration files into different UI compoentns of `knowledge base` page.
 
-```{figure} brainkbdocs-headerconfig.png
-:name: brainkbdocs-headerconfig
-Landing page header configuration using `config-home.yaml`.
-```
+ 	{ref}`content:references:configurationfilesui` section provides further details on the configuration files used in BrainKB UI.
 
-```{figure} brainkbdocs-statistics_structured_box.png
-:name: brainkbdocs-statistics_structured_box
-Landing page configuration of structured models and statics cards using `config-home.yaml`.
-```
+	 ```{important} 
+	 In order to apply the BrainKB UI to your specific use cases, you will need to modify the configuration files (refer to Section {ref}`content:references:configurationfilesui`) as per your requirements.
+	```
 
-```{figure} brainkbdocs-knowledgebasepage.png
-:name: brainkbdocs-knowledgebasepage
-Configuration of the knowledge base page using `config-knowledgebases.yaml`.
-```
+	```{figure} brainkbdocs-headerconfig.png
+	:name: brainkbdocs-headerconfig
+	Landing page header configuration using `config-home.yaml`.
+	```
+
+	```{figure} brainkbdocs-statistics_structured_box.png
+	:name: brainkbdocs-statistics_structured_box
+	Landing page configuration of structured models and statics cards using `config-home.yaml`.
+	```
+
+	```{figure} brainkbdocs-knowledgebasepage.png
+	:name: brainkbdocs-knowledgebasepage
+	Configuration of the knowledge base page using `config-knowledgebases.yaml`.
+	```
 
 
 ## Running in Non-Containerized Development Mode
@@ -70,28 +79,34 @@ To run in a production mode first you need to build the application and start. R
 
 
 ## Running in Containerized Mode
-
-## Known Issues
-
-Especially with the Google based authentication, even after successful setup, you might get error regarding mismatch redirect URI, as shown in {numref}`google_oauth_error`, thereby preventing you to log in. This is because unlike GitHub-based OAuth, where you can redirect to the pages that one desire, e.g., home page, the redirect URI in case of Google needs to be specific.
-
-```{figure} error_oauth_google.png
-:name: google_oauth_error
-Unable to login with Google.
-```
-
-To fix this issue, set the redirect URI as ```https://{YOUR_DOMAIN}/api/auth/callback/google```. In ```YOUR_DOMAIN``` is:
-- ```https://localhost:3000/api/auth/callback/google``` development mode
-- in production, replace ```YOUR_DOMAIN``` with registered domain name
-
-More information regarding these callbacks can be obtained from NextJS website at 
-[https://next-auth.js.org/providers](https://next-auth.js.org/providers).
-
-
+Todo
 
 (content:references:configurationfilesui)=
 ## Configuration Files
+BrainKB is designed to be configurable so that it can be easily reusable in other use cases. To make the BrainKB UI reusable, we have adopted a configure file approach using YAML-based configuration files (or LinkML schemas (or ontologies) expressed in YAML).  In the subsections below, we describe different configuration files and schemas that are used in BrainKB UI.
+
 ### config-home.yaml
+The `config-home.yaml` file is used to configure the home page, aka the landing page. The configuration file shown below is the default one that is being used in the current implementation.
+
+The following is a description of the various components of the configuration files.
+
+- **headersboxpage**: The configuration details for the titles and subtitles of various sections of the landing page.
+	- `name`: The human readable name. Is not used in the UI.
+	- `slug`: A unique component is used to identify the particular headerbox.
+	- `title`: The title text that you wish to appear in the UI.
+	- `subtitle`: The subtitle text that you wish to appear in the UI.
+- **structuredmodelsbox**: The configuration for the schema (or ontology) information.
+	- `name`: The human readable name. Is not used in the UI.
+	- `slug`: A unique component is used to identify the particular card (or box).
+	- `title`: The title text for the card (or box) that you wish to appear in the UI.
+	- `description`: The short description that you wish to appear in the UI.
+	- `links`: The navigation link for the models (or schemas) documentation page. 
+- **boxiconsstatisticscount**: The configuration for the knowledge base statistics.
+	- `name`: The human readable name. Is not used in the UI.
+	- `slug`: A unique component is used to identify the particular card (or box).
+	- `short_description`: The short description that you wish to appear in the UI.
+	- `sparql_query`: The SPARQL query that is to be executed to get the statistics.
+
 ```
 headersboxpage:
   - name: "brainkb main page"
@@ -142,8 +157,7 @@ boxiconsstatisticscount:
         ?s biolink:iri ?o.
       }
   - name: "Donor"
-    slug: "donor"
-    slugcategory: "counts"
+    slug: "donor" 
     short_description: "A person or organism that is the source of a biological sample for scientific study. Many biological samples are generated from a single donor."
     sparql_query: |-
       PREFIX bican: <https://identifiers.org/brain-bican/vocab/> 
@@ -154,7 +168,6 @@ boxiconsstatisticscount:
       }
   - name: "Structure"
     slug: "structure"
-    slugcategory: "counts"
     short_description: ""
     sparql_query: |-
       PREFIX bican: <https://identifiers.org/brain-bican/vocab/>  
@@ -163,8 +176,7 @@ boxiconsstatisticscount:
         ?id bican:structure ?o; 
       }
   - name: "Library Aliquot"
-    slug: "libraryaliquot"
-    slugcategory: "counts"
+    slug: "libraryaliquot" 
     short_description: "One library in the library pool."
     sparql_query: |-
       PREFIX bican: <https://identifiers.org/brain-bican/vocab/> 
@@ -239,4 +251,23 @@ pages:
     display_column_first: "id"
     display_column_second: "label"
     display_column_third: "category"
-```
+```
+
+## Known Issues
+
+- **OAuth:** Especially with the Google based authentication, even after successful setup, you might get error regarding mismatch redirect URI, as shown in {numref}`google_oauth_error`, thereby preventing you to log in. This is because unlike GitHub-based OAuth, where you can redirect to the pages that one desire, e.g., home page, the redirect URI in case of Google needs to be specific.
+
+	```{figure} error_oauth_google.png
+	:name: google_oauth_error
+	Unable to login with Google.
+	```
+
+	To fix this issue, set the redirect URI as ```https://{YOUR_DOMAIN}/api/auth/callback/google```. In ```YOUR_DOMAIN``` is:
+	- ```https://localhost:3000/api/auth/callback/google``` development mode
+	- in production, replace ```YOUR_DOMAIN``` with registered domain name
+
+	More information regarding these callbacks can be obtained from NextJS website at 
+	[https://next-auth.js.org/providers](https://next-auth.js.org/providers).
+
+- 
+