Differences

This shows you the differences between two versions of the page.

--- medal-data [2021/12/17 09:12] – arnaud_poletto
+++ medal-data [2024/01/12 11:35] (current) – [medAL-data User Guide and Troubleshooting] Sylvain
@@ Line 1: / Line 1: @@
 ====== medAL-data Documentation ======
-===== medAL-data System =====
+medAL-//data// is a National server that stores local data for the clinical follow-up and feeds dashboards with completely anonymized data.
-==== Purpose and Scope ====
-This document lists instructions to setup a medAL//-data// server instance and is intended to be read carefully by the entities involved in setting up the various components of the medAL suite.
+===== medAL-data Setup and Management =====
+  * [[medal-data:setup|medAL-data setup]]
+  * [[medal-data:server-block-setup|Server blocks setup]]
+  * [[medal-data:printer-setup|Printer setup for stickers]]
+  * [[medal-data:integration-details|Integration details]]
+  * {{ ::20220112_medaldata_doc_installing_and_configuring_passport.pdf |"Passport" documentation}}
+  * Data model (updated 20230123):
+{{ :medal-data:medal-data.png?400 |}}
-==== Initial Requirements ====
-- Linux Server. Minimal requirements:
-  - 8GB RAM
-  - 300GB Disk capacity
-  - Operating System: Ubuntu >= 18.04
-- Controlling workstation (Linux / MacOS / Windows) with the following installed:
-  - git version control software (see https://git-scm.com/)
-  - bash terminal (for windows see : https://gitforwindows.org/)
-- Domain Name (In the installation we will use the name //example.com//) pointing to the server's IP address.
+===== medAL-data User Guide and Troubleshooting =====
+  * [[medal-data:user-guide| medAL-data user guide]]
+  * [[medal-data:variables|medAL-data environment variables]]
+  * [[medal-data:administrator-guide| medAL-data administrator guide]]
+  * [[medal-data:database|medAL-data database schema]]
+  * [[medal-data:troubleshooting-guide| medAL-data troubleshooting guide]]
+  * [[medal-data:monitoring-guide| medAL-data monitoring guide]]
+  * [[medal-data:data-flow| medAL-data Data Flow]]
+  * [[medal-data:icf| medAL-data Informed consent form management]]
-===== Manual Installation =====
-==== Environment Setup ====
-Open up two terminals **[t_local]** and **[t_remote]** on the controlling workstation, on **[t_remote]** connect to the root account of the remote server using ssh:
-<code>ssh root@example.com</code>
-=== Dokku Installation on Remote Server ===
-  - **[t_remote]** Install dokku with the following commands: \\ <code>
-wget https://raw.githubusercontent.com/dokku/dokku/v0.24.10/bootstrap.sh
-sudo DOKKU_TAG=v0.24.10 bash bootstrap.sh
-</code> To get the latest verison go to https://dokku.com/docs/getting-started/installation/
-  - **[t_local]** On the local workstation, open a browser and head to your server domain ''example.com'' where you will be able to setup the public SSH key used when deploying the source code to the server and optionnaly enable virtual hosting on the server:
-   -  If you already have a ssh key configured for git on your local workstation, then copy the value of the public key and paste in the dialog on dokku's web interface. If you already have a public key then you can copy the value output from the command: \\ <code>
-cat ~/.ssh/id_rsa.pub
-</code>, or generate a new one using: \\ <code>
-ssh-keygen -t rsa
-</code>
-   -  Enter your domain name ''example.com'' in the corresponding dialog box
-==== Application Deployment ====
-  - **[t_remote]** Run the following commands to create and configure the dokku app for the medAL//-data// server: \\ <code>
-# Create the App
-dokku apps:create medal-data
-# Install the postgres DB plugin
-sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
-# Create Database
-dokku postgres:create medal-data-db
-# Link the App to the database
-dokku postgres:link medal-data-db medal-data
-# Set Config variables for Laravel
-dokku config:set medal-data DB_CONNECTION=postgres
-# Add the PHP buildpack to the apps config
-dokku config:set medal-data BUILDPACK_URL="https://github.com/heroku/heroku-buildpack-php"
-# Configure the storage folder of the server
-mkdir -p /var/lib/dokku/data/storage/medal-data
-mkdir -p /var/lib/dokku/data/storage/medal-data/framework
-mkdir -p /var/lib/dokku/data/storage/medal-data/framework/sessions
-mkdir -p /var/lib/dokku/data/storage/medal-data/framework/cache
-mkdir -p /var/lib/dokku/data/storage/medal-data/framework/views
-# give rights to herokuish
-chown -R 32767:32767 /var/lib/dokku/data/storage/medal-data
-dokku storage:mount medal-data /var/lib/dokku/data/storage/medal-data:/app/storage
-# set the scale of the application
-dokku ps:scale medal-data web=1 worker=1
-</code>
-  - **[t_local]** On the local workstation, clone the source code of the medal-data server from the bitbucket repository: \\ <code>
-git clone https://informatique_unisante@bitbucket.org/wavemind_swiss/liwi-main-data.git</code>, and navigate to the project folder: \\ <code>
-cd liwi-main-data </code>
-  - **[t_local]** Do a copy the ''dokku.env.example'' file and name it ''dokku.env''. Fill out the values depending on your desired configuration. Then copy the file content to your clipboard.
-  - **[t_remote]** On the remote server, paste the content at the end of the following file: ''/home/dokku/medal-data/ENV''.
-  - **[t_local]** Link and deploy the server with the following git commands (replace **example.com** with your own domain name): \\ <code>
-git remote add dokku dokku@example.com:medal-data
-git push dokku master
-</code> If the push did not work, then make sure you have correctly set up the SSH key on the dokku server using the web interface (more information on https://dokku.com/docs/deployment/user-management/).
-. **[t_remote]**: Back on the remote server, run the following command to set the APP_KEY environment variable:
-   ```bash
-   dokku config:set medal-data APP_KEY=$(dokku run medal-data php artisan --no-ansi key:generate --show) --no-restart
-   ```
-. **[t_remote]**: Also run the following command to make sure that Laravel's passports encryption keys are properly generated:
-   ```bash
-   dokku run medal-data php artisan passport:keys
-   ```
-. **[t_remote]**: Finally, if needed migrate and seed the database using:
-   ```bash
-   dokku run medal-data php artisan migrate:fresh --seed --force
-   ```
-   If you wish to only migrate the database then run:
-   ```bash
-   dokku run medal-data php artisan migrate --force
-   ```
-=====Health Facility Setup & Device Registration=====
-In this section, we show how to use the new interface to create health facilities and assign to them devices such as medAL-*reader* and medAL-*hub* as well as specific algorithm versions that can fetched by authorized devices.
-====Health Facility Creation====
-To start, login with a user which has the `Logistician` role. (if the database is seeded then there is a default role with u: `logistician@dynamic.com`, pwd: `1234`) The main logistician dashboard gives access to the management of health facilities and devices which can be created and edited freely.
-<img src="./assets/logistician_panel.png" alt="log_panel" style="zoom:60%;" />
-When creating a medal-*hub* device, a redirection URL must be specified in order to enroll the device later on. This redirect URL should correspond to the address of the device (+ endpoint TBD) on the local network when registering it.
-====Device Assignment====
-To assign a Device to a health facility, head to the health facility management panel and click on the `Devices` button on the row corresponding to the health facility. A window will open up allowing to assign free devices to this health facility.
-<img src="./assets/assign_devices.png" alt="dev" style="zoom:60%;" />
-====Algorithm Version Assignment====
-Similarly, medAL-*creator* algorithm versions can be assigned to health facilities by clicking the `Algorithms` button on the row corresponding to the health facility. The window will show two dropdown lists where an algorithm and corresponding version can be assigned. When a version is replaced, the older versions will appear in the table below. Note that choosing a version for which a *json* has not been properly generated on the *creator* server will result in an error.
-<img src="./assets/assign_versions.png" alt="ver" style="zoom:60%;" />
-===Device API===
-When devices and an algorithm version is assigned to a health facility, devices can request access tokens from the medAL-*data* server in order to authenticate to medAL-*data*'s protected API. The full API is documented in the [Postman Collection]("./device_api.json")
-===Getting a Token with PKCE in Postman===
-In order to get a token and a refresh token, the PKCE OAuth flow must be used. For the example above, this can be tested using the postman collection's PKCE request. Head to the **Authorization** tab in the request and fill out the form such that the urls points to the medAL-*data* server, the Client ID field corresponds to the Auth ID of the device and the Redirect URL should be the same than the one set for the device. To check what redirect URL is assigned to the device, head to the devices tab and click on the `View` button of the corresponding device to show all the details. When the form is filled out in Postman, click on the `Get New Access Token` button to start the PKCE flow which will redirect you to the login page (where you have to login using the user credentials used to create the device). A prompt will ask you to grant access to the device, press `Ok` and then you should receive a token and refresh token.
-===Protected Routes===
-The protected routes allow devices to:
-- Upload medical cases (to be integrated still)
-- Fetch information from the health facility such that the pin code and hub IP
-- Upload its own device information such as mac address, os etc..
-- Fetch the json of the algorithm version that is assigned to this health facility
-You can try out these routes using the Postman collection replacing the `token` variable with the one received using the PKCE flow.
-====Passport Installation====
-In order to install passport we had to make slight changes of the laravel version currently used by this server. Originally, the `composer.json` file had the following version:
-```json
- "require": {
-...
-        "laravel/framework": "6.0.*",
-...
-    },
-```
-Which we changed to:
-```json
-"require": {
-    ....
-        "laravel/framework": "^6.20.26",
-    ...
-    },
-```
-for the passport installation to work properly. After changing the `composer.json` we run `composer update` followed by `composer require laravel/passport` which successfully installed passport's back-end routes. The routes used for Passport are then registered in the `AuthServiceProvider.php` provider class where we only used the routes necessary for our desired functionality.
-=====Database model=====
-{{::medal-data-newmodel2022.png?600|}}