Major documentation refactoring. (#162)

* Removed the old mip script * Moved all Kubernetes doc in /doc. * Move /documentation to /config/keycloak/doc * Move NewDataRequirements to /doc * Update anchor for UsersConfiguration.md * Enhanced hyperlink visibility to improve user experience. * Reformatted landing page Readme.md into a table of contents style to enhance the user experience. --------- Co-authored-by: Cedric Rochat <[email protected]> Co-authored-by: David Medioni <[email protected]> Co-authored-by: kfilippopolitis <[email protected]>
HBPMedical · Nov 8, 2023 · cc5bc9d · cc5bc9d
1 parent da83a26
commit cc5bc9d
Show file tree

Hide file tree

Showing 23 changed files with 162 additions and 12,756 deletions.
diff --git a/README.md b/README.md
@@ -1,45 +1,14 @@
-# Medical Informatics Platform (MIP), deployment
-
-This is the MIP main repository.
-
-Here, you have everything to deploy and operate a *local* or a *federated* MIP.  
-As this repository can be used to deploy any type of MIP, it can also just be used as an "installer", and be deleted once the MIP is installed. i.e. for a *local* installation, using the *mip* script to install the MIP will clone this repository in /opt/mip-deployment for the operating purpose, and the *mip* script will also be callable from /usr/local/bin.  
-Then, if you cloned this repository in your home for the installation purpose, you don't need it any further when the install process is done.
-
-## Requirements
-### Hardware
-* 40 GB HDD
-* 8 GB RAM
-* 2 CPU Cores
-
-### Software
-* Ubuntu Server 20.04 (minimal installation, without GUI)
-
-## <a id="Components">MIP Components</a>
-The "short names" listed here represent the different MIP components, as well as recognized component names by the *mip* script.
-* [frontend](https://github.com/HBPMedical/portal-frontend): The "Web App"
-* [gateway](https://github.com/HBPMedical/gateway): "Middleware" layer between the MIP Frontend and a federated analytic engine
-* [portalbackend](https://github.com/HBPMedical/portal-backend): The "Backend API" supports the Web App
-* [portalbackend_db](https://github.com/docker-library/postgres): The portal backend's database
-* [keycloak](https://github.com/keycloak/keycloak-containers): The "AuthN/AuthZ" system, based on KeyCloak (this component usually doesn't run in a *federated* MIP, as an "external" KeyCloak service does the job). In case this *local* "embedded" component is used, you may need to know some <a id="UsersConfiguration">details</a>, which you can find [here](documentation/UsersConfiguration.md)
-* [keycloak_db](https://github.com/docker-library/postgres): The KeyCloak's database, required only if the *keycloak* component needs to be used
-* [create_dbs](https://github.com/HBPMedical/docker-create-databases): The *one shot* container which creates and populates the DBs when required
-* [exareme2](https://github.com/madgik/exareme2): The "Analysis Engine" offers the federated (also used by the *local* MIP) analysis capabilities
-
-## Deployment
-### <a id="LocalDeployment">Local</a>
-The *local* MIP is designed to run on a single machine.  
-In this context, all the MIP components (understand: containers) run on the same hypervisor.  
-For the security (AuthN/AuthZ), Keycloak comes as a MIP component.
-
-[Here](doc/Readme.md), you can find details about deploying and operating the *local* MIP.
-
-### <a id="FederatedDeployment">Federated</a>
-The *federated* MIP is designed to run on multiple machines.  
-In this context, and as we usually use an external KeyCloak service, the components which run on the same machine are less than for the *local* deployment.
-
-[Here](Federation/doc/Readme.md), you can find details about deploying and operating the *federated* MIP.
-
-
-# Acknowledgement
+# Medical Informatics Platform (MIP)
+
+## Deployment Documentation Contents
+1. [Requirements for new data, to join the federation](doc/NewDataRequirements.md)
+1. [Deployment Requirements](kubernetes/README.md#requirements)
+1. [Deployment Components](kubernetes/README.md#components)
+1. [Setting up the data](kubernetes/README.md#taking-care-of-the-medical-data)
+1. [Deploying the stack](kubernetes/README.md#configuration)
+1. [Configuring new users](doc/keycloak/UsersConfiguration.md)
+1. [Authorization for new user](doc/keycloak/UserAuthorizations.md)
+1. [Backup and Recovery](doc/BackupAndRecovery.md)
+
+## Acknowledgement
 This project/research received funding from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Framework Partnership Agreement No. 650003 (HBP FPA).
diff --git a/kubernetes/doc/BackupAndRecovery.md → doc/BackupAndRecovery.md b/kubernetes/doc/BackupAndRecovery.md → doc/BackupAndRecovery.md
@@ -5,7 +5,7 @@
 MIP is currently deployed using kubernetes and the data that need to be persisted are mounted in volumes.
 The data that need to be persisted are located ONLY in the central node.
 
-The volumes that are created in the host machine can be seen [here](../values.yaml) as storage data paths.
+The volumes that are created in the host machine, are listed in the [storage data paths section of the `values.yaml` file](../kubernetes/values.yaml).
 
 The folders that currently need to be backed up are the following:
 1. The portal-backend stored data under `/opt/mip-deployment/.stored_data`

diff --git a/kubernetes/doc/MIP_Configuration.png → doc/MIP_Configuration.png b/kubernetes/doc/MIP_Configuration.png → doc/MIP_Configuration.png
diff --git a/kubernetes/doc/MIP_Configuration.vsdx → doc/MIP_Configuration.vsdx b/kubernetes/doc/MIP_Configuration.vsdx → doc/MIP_Configuration.vsdx
diff --git a/doc/MIP_Local_Configuration.png b/doc/MIP_Local_Configuration.png
diff --git a/doc/MIP_Local_Configuration.vsdx b/doc/MIP_Local_Configuration.vsdx
diff --git a/doc/MIP_Local_Deployment.png b/doc/MIP_Local_Deployment.png
diff --git a/doc/MIP_Local_Deployment.vsdx b/doc/MIP_Local_Deployment.vsdx
diff --git a/documentation/NewDataRequirements.md → doc/NewDataRequirements.md b/documentation/NewDataRequirements.md → doc/NewDataRequirements.md
@@ -21,7 +21,7 @@ The metadata file **must** follow these rules:
 * The `dataset` CDE is required.
 * In the parent dictionary there will be a `version` property, of string format.
 
-An example can be seen [here](../data/dementia/CDEsMetadata.json).
+An example can be seen at [CDEs Medatadata](../data/dementia/CDEsMetadata.json).
 
 After adding the CDEsMetadata file you can add your data the same way as adding **New Data on existing Pathology**.
 
@@ -49,10 +49,10 @@ If you want to add a new pathology on MIP then you need to create a new folder i
 * The CDEsMetadata.json file
 * and the CSVs containing the data.
 
-# Loading data on Exareme2
+# Local Validation of New Data
 
-There is more detailed documentation on adding data to exareme2 [here](https://github.com/madgik/Exareme2/blob/master/kubernetes/docs/ImportNodeData.md).
+For detailed instructions on validating the `CDEsMetadata.json` file and the CSV files you are working with, please refer to the comprehensive documentation available on the [MIPDB GitHub repository](https://github.com/madgik/mipdb/).
 
-# Validation Script
+# Loading data on Exareme2
 
-Comprehensive documentation for validating the CDEsMetadata.json file and the CSV files you are working with can be found [here](https://github.com/madgik/mipdb/blob/2.4.6/README.md).
+For detailed instructions on adding data to Exareme2, please consult the [Exareme2 documentation on importing node data](https://github.com/madgik/Exareme2/blob/master/kubernetes/docs/ImportNodeData.md).
diff --git a/doc/Readme.md b/doc/Readme.md
diff --git a/documentation/CreateLocalUser.md → doc/keycloak/CreateLocalUser.md b/documentation/CreateLocalUser.md → doc/keycloak/CreateLocalUser.md
@@ -1,5 +1,3 @@
-[Users Configuration](UsersConfiguration.md#CreateLocalUser) -> `Create a New User`
-
 ### Create a User
 
 Login to the keycloak console on http://{MIP_IP}/auth/admin/ with the administrator credentials.

diff --git a/documentation/ExportingKeycloakState.md → doc/keycloak/ExportingKeycloakState.md b/documentation/ExportingKeycloakState.md → doc/keycloak/ExportingKeycloakState.md
diff --git a/documentation/UserAuthorizations.md → doc/keycloak/UserAuthorizations.md b/documentation/UserAuthorizations.md → doc/keycloak/UserAuthorizations.md
@@ -1,5 +1,3 @@
-[Users Configuration](UsersConfiguration.md#UserAuthorizations) -> `User Authorizations`
-
 ## User Authorizations
 
 A user can be authorized on two different aspects:

diff --git a/documentation/UsersConfiguration.md → doc/keycloak/UsersConfiguration.md b/documentation/UsersConfiguration.md → doc/keycloak/UsersConfiguration.md
@@ -1,7 +1,5 @@
-[MIP Deployment](../README.md#UsersConfiguration) -> `Users Configuration`
-
 ## Users Configuration
-By default MIP has 2 users, one is an administrator and one is a mip user.
+By default, MIP has 2 users, one is an administrator and one is a mip user.
 
 First of all, you should change the administrator credentials, from this url: http://{MIP_IP}/auth/realms/master/account/password
 
@@ -12,7 +10,7 @@ password: Pa55w0rd
 ```
 
 ### Create a New User
-<a id="CreateLocalUser">Follow</a> this [guide](CreateLocalUser.md).
+Follow this [guide](CreateLocalUser.md).
 
 ### User Authorizations
-<a id="UserAuthorizations">Follow</a> this [guide](UserAuthorizations.md).
+Follow this [guide](UserAuthorizations.md).
diff --git a/documentation/images/addRole.png → doc/keycloak/images/addRole.png b/documentation/images/addRole.png → doc/keycloak/images/addRole.png
diff --git a/documentation/images/addUser.png → doc/keycloak/images/addUser.png b/documentation/images/addUser.png → doc/keycloak/images/addUser.png
diff --git a/documentation/images/joinGroup.png → doc/keycloak/images/joinGroup.png b/documentation/images/joinGroup.png → doc/keycloak/images/joinGroup.png
diff --git a/documentation/PortsConfiguration.md b/documentation/PortsConfiguration.md
diff --git a/documentation/SwitchBetweenKeycloakServers.md b/documentation/SwitchBetweenKeycloakServers.md