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.

- Linux Server. Minimal requirements:

1. 8GB RAM
2. 300GB Disk capacity
3. Operating System: Ubuntu >= 18.04

- Controlling workstation (Linux / MacOS / Windows) with the following installed:

1. git version control software (see https://git-scm.com/)
2. 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.

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:

ssh root@example.com

1. [t_remote] Install dokku with the following commands:
   

   wget https://raw.githubusercontent.com/dokku/dokku/v0.24.10/bootstrap.sh
   sudo DOKKU_TAG=v0.24.10 bash bootstrap.sh 

   To get the latest verison go to https://dokku.com/docs/getting-started/installation/

1. [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:
2. 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:
   

   cat ~/.ssh/id_rsa.pub

   , or generate a new one using:
   

   ssh-keygen -t rsa

3. Enter your domain name example.com in the corresponding dialog box

1. [t_remote]: Run the following commands to create and configure the dokku app for the medal-*data* server

   # 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

2. [t_local]: On the local workstation, clone the source code of the medal-data server from the bitbucket repository by running the command `git clone https://informatique_unisante@bitbucket.org/wavemind_swiss/liwi-main-data.git` and navigate to the project folder `cd liwi-main-data`. 3. [t_local]: copy the `dokku.env.example` file in this folder and fill out the values depending on your desired configuration. Then copy the file contents to your clipboard. 4. [t_remote]: On the remote server paste the contents at the end of the following file: `/home/dokku/medal-data/ENV`. 5. [t_local]: Link and deploy the server with the following git commands (replace example.com with your own domain name):

 ```bash
 git remote add dokku dokku@example.com:medal-data
 git push dokku master
 ```
 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/)

6. [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
 ```

7. [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
 ``` 

8. [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
 ```

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.

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.

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%;” />

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%;” />

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”)

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.

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.

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.