medal-hub
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| medal-hub [2021/12/14 15:44] – arnaud_poletto | medal-hub [2022/01/14 16:27] (current) – Alan Vonlanthen | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== medAL-hub Documentation ====== | ====== medAL-hub Documentation ====== | ||
| - | ==== About medAL-hub | + | The purpose of medAL-//hub// is 3-fold: |
| + | - Relay between the tablets, thus allowing to start a consultation on a tablet and finish it on another one (client-server). | ||
| + | - Local database for the clinical data. | ||
| + | - Hub for the data synchronisation with the National server (medAL-// | ||
| - | The purpose of medAL-hub is 3-fold: | ||
| - | - Relay between the tablets, thus allowing to start a consultation on a tablet and finish it on another one (Client server) | ||
| - | - Local database for the clinical data | ||
| - | - Hub for the data synchronisation with the National server (medAL-data) | ||
| - | ==== medAL-hub Installation ==== | ||
| - | === Prerequisite === | ||
| - | Follow the procedure given in SOP: {{ : | ||
| - | At this point, you should be able to connect to the following wifi networks: \\ | ||
| - | // | ||
| - | // | ||
| - | === Material Needed | + | ===== medAL-hub Setup and Management ===== |
| - | You will need the following material: | + | |
| - | * Raspberry PI 4 (For convenience and ease, it will be shortened to RasPi [[https:// | + | |
| - | * A MicroSD card [[https:// | + | |
| - | * An SD card reader for the PC [[https:// | + | |
| - | * An HDMI to micro-HDMI cable (NOT mini) [[https:// | + | |
| - | * A PowerBank (5Vx3A (15W) output) [[https:// | + | |
| - | * A Power Adapter (USB + Power) [[https:// | + | |
| - | * An internet connection (either cable or Wi-Fi) | + | |
| - | * A PC connected to internet, with admin rights | + | |
| - | * A screen with HDMI connection | + | |
| - | * A USB keyboard | + | |
| - | === SD Card Setup === | + | * [[medal-hub:setup|medAL-hub setup]] |
| - | | + | |
| - | - Download the HypriotOS image: https:// | + | |
| - | | + | |
| - | | + | |
| - | | + | |
| - | | + | |
| - | === RasPI Setup === | ||
| - | - Put the SD card back in the RasPI. | ||
| - | - Connect the RasPI to the following: | ||
| - | * HDMI (0) \\ {{:: | ||
| - | * Ethernet (if present) | ||
| - | * A Keyboard | ||
| - | * A Screen | ||
| - | * The PowerBank | ||
| - | - Wait until you see “login” and a blinking underscore (after about 4 minutes). That means you are ready to start. If no login then repeat steps above. | ||
| - | == WiFi Setup == | ||
| - | Enter the credentials (press //Enter// between each and be careful: **the keyboard is UK by default**): \\ | ||
| - | Username: //pirate// \\ | ||
| - | Password: //hypriot// | ||
| - | The next step is to create the '' | ||
| - | < | + | ===== medAL-hub User Guide and Troubleshooting ===== |
| - | If you are configuring the hub for an offline facility, also add the following line: | + | * [[medal-hub:user-guide| medAL-hub user guide]] |
| - | < | + | * [[medal-hub: |
| - | After that, we have to give a name to each of the network configurations. In order to do that, open ''/ | ||
| - | < | ||
| - | And add the two '' | + | ===== medAL-hub Data Sync Schedule |
| - | < | + | There are 2 scripts on the hub for syncing: |
| - | ssid=”health_facility_dynamic” | + | - script #1 runs everyday at 4PM and sends all the cases closed but unsynced to the server |
| - | #psk=”...” | + | - script #2 runs every minute and sends all the cases closed for more than 25 hours that have not yet been sent to the server |
| - | psk=… | + | * huge caveat :!:: the raspberry pi does not have a physical clock. Meaning, everytime it loses power, it does not know what time it is until it gets the time from the internet |
| - | id_str=”hf” | + | |
| - | } | + | |
| - | network={ | + | |
| - | ssid=”mobile_dynamic” | + | |
| - | #psk=”...” | + | |
| - | psk=… | + | |
| - | id_str=”mobile” | + | |
| - | } | + | |
| - | </ | + | |
| - | Save file using 1. Control X 2. Confirm Y 3. Press Enter | ||
| - | After that, we have to link the wpa_supplicant.conf configuration to the wlan0 interface. Open / | ||
| - | < | ||
| - | And edit the file to make it exactly as below: | ||
| - | < | ||
| - | #source / | ||
| - | allow-hotplug wlan0 | ||
| - | iface wlan0 inet manual | ||
| - | wpa-roam / | ||
| - | iface hf inet dhcp | ||
| - | iface mobile inet dhcp | ||
| - | </ | ||
| - | Save file using 1. Control X 2. Confirm Y 3. Press Enter | ||
| - | After that, we can activate the wlan0 interface: | ||
| - | < | ||
| - | |||
| - | Make sure to save the changes and reboot | ||
| - | < | ||
| - | |||
| - | The device should now be connected to the internet. | ||
| - | < | ||
| - | |||
| - | in order to verify this. (Control C to exit ping command). | ||
| - | Now that the connection is established, | ||
| - | < | ||
| - | |||
| - | and take note of the following values (under wlan0 interface) | ||
| - | * Unordered List Iteminet (the assigned IP) | ||
| - | * netmask | ||
| - | * broadcast | ||
| - | These values will be useful later. Run: | ||
| - | < | ||
| - | |||
| - | And take note of the nameserver address (the first address that appears). | ||
| - | Run: | ||
| - | < | ||
| - | |||
| - | Make the necessary changes (under hf interface): | ||
| - | < | ||
| - | |||
| - | allow-hotplug wlan0 | ||
| - | iface wlan0 inet manual | ||
| - | wpa-roam / | ||
| - | |||
| - | iface hf inet static | ||
| - | address 178.17.54.136 | ||
| - | netmask 255.255.255.0 | ||
| - | network 178.17.54.0 | ||
| - | broadcast 178.17.54.255 | ||
| - | gateway 178.17.54.1 | ||
| - | dns-nameservers 178.17.54.1 | ||
| - | iface mobile inet dhcp | ||
| - | </ | ||
| - | |||
| - | Replace the relevant values with the ones from the previous step. The network value is the bitwise AND of address and netmask. The gateway value is usually the network value with a 1 at the end. The dns-nameservers address is the address that we saw in < | ||
| - | |||
| - | Make sure to save the changes and reboot | ||
| - | < | ||
| - | |||
| - | The connection should now be established (again). | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | == Application Setup == | ||
| - | Clone the repository and checkout the master branch | ||
| - | < | ||
| - | cd liwi-local-data | ||
| - | git checkout master | ||
| - | </ | ||
| - | |||
| - | Create the environment file and set the health facility ID. | ||
| - | < | ||
| - | nano .env | ||
| - | </ | ||
| - | |||
| - | Install the project nginx, php and other requirements of the project | ||
| - | < | ||
| - | sudo apt upgrade | ||
| - | sudo apt install nginx php composer php-zip php-xml php-fpm php-pgsql | ||
| - | </ | ||
| - | |||
| - | Restart: | ||
| - | < | ||
| - | |||
| - | Start the docker container, install pendencies and prepare the database | ||
| - | < | ||
| - | composer install | ||
| - | php artisan key: | ||
| - | php artisan migrate | ||
| - | </ | ||
| - | |||
| - | Open the nginx configuration file | ||
| - | < | ||
| - | |||
| - | And insert the following server block (right after the # Virtual Host Configs) | ||
| - | |||
| - | The two #include statements after the server block should be commented out | ||
| - | < | ||
| - | #include / | ||
| - | #include / | ||
| - | server { | ||
| - | listen 80; | ||
| - | listen 443 ssl; | ||
| - | ssl_certificate / | ||
| - | ssl_certificate_key / | ||
| - | # | ||
| - | root / | ||
| - | add_header X-Frame-Options " | ||
| - | add_header X-Content-Type-Options " | ||
| - | index index.php; | ||
| - | charset utf-8; | ||
| - | location / { | ||
| - | try_files $uri $uri/ / | ||
| - | } | ||
| - | location = / | ||
| - | location = / | ||
| - | error_page 404 /index.php; | ||
| - | client_max_body_size 0; | ||
| - | location ~ \.php$ { | ||
| - | fastcgi_pass unix:/ | ||
| - | fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; | ||
| - | include fastcgi_params; | ||
| - | } | ||
| - | location ~ / | ||
| - | deny all; | ||
| - | } | ||
| - | } | ||
| - | </ | ||
| - | |||
| - | We can verify that the nginx configuration is valid using the following command: | ||
| - | < | ||
| - | |||
| - | After that, we have to change the permissions of the project folder so that each component of the application (the web server and the database) can access the required files. | ||
| - | < | ||
| - | sudo chown -R root:root / | ||
| - | sudo usermod -a -G www-data pirate | ||
| - | </ | ||
| - | |||
| - | |||
| - | Restart the docker container | ||
| - | < | ||
| - | docker-compose up -d | ||
| - | </ | ||
| - | |||
| - | Restart nginx | ||
| - | < | ||
| - | |||
| - | Go to [[http://< | ||
| - | |||
| - | |||
| - | ==== medAL-hub Maintenance Setup ==== | ||
| - | |||
| - | == Update script == | ||
| - | We are now going to create a script to update the application from the git repository | ||
| - | < | ||
| - | touch ~/update.sh | ||
| - | chmod +x ~/update.sh | ||
| - | nano ~/update.sh | ||
| - | </ | ||
| - | |||
| - | The content of the script should look like this: | ||
| - | |||
| - | < | ||
| - | #!/bin/sh | ||
| - | cd / | ||
| - | docker-compose down | ||
| - | git pull | ||
| - | docker-compose up -d | ||
| - | composer install | ||
| - | php artisan key: | ||
| - | php artisan migrate | ||
| - | </ | ||
| - | |||
| - | == Crontab Setup == | ||
| - | We need to configure cron jobs so that Laravel can run synchronization jobs and that the update script gets executed everyday. Open the crontab with sudo crontab –e and add the following jobs: | ||
| - | < | ||
| - | * * * * * php / | ||
| - | 30 16 * * * / | ||
| - | </ | ||
| - | |||
| - | The exact time of the update can be adjusted based on the health facility requirements (in this example it is set to update at 16:30 everyday). | ||
| - | |||
| - | |||
| - | == Sync configuration == | ||
| - | Open the configuration file for synchronization (nano config/ | ||
| - | |||
| - | * offline_mode and daily_sync_time | ||
| - | * * Choose false for offline_mode if a reliable connection is expected to be available throughout the day. In that case, the hub makes one attempt of pushing the cases to main data every day at a fixed time. The exact time at which the synchronization happens can be configured with daily_sync_time. | ||
| - | * * Choose true if a reliable connection is only available from time to time, e.g. during a few minutes each day. In that case, the hub will attempt to push the cases as soon as a connection can be established with the main data server. | ||
| - | * sync_url and sync_domain | ||
| - | * * These values are used to reach the main data server. | ||
| - | * offline_outofsync_thr and online_outofsync_thr | ||
| - | * * This value is the number of hours after which the cases are considered out-of-sync (starting from creation time). Synchronization will be triggered as soon as any closed case is out-of-sync and connection is available. The value for online mode should to be much higher than the one for offline mode because a reliable connection is expected to be available in online mode. For this reason, cases in online mode only become out-of-sync when the daily scheduled synchronization cannot take place for some reason. | ||
| - | |||
| - | == Synchronization Using a Mobile Hotspot (Offline facilities) == | ||
| - | In the case where no connection is available at the health facility, it is possible to perform a synchronization with the help of a mobile phone with a mobile internet connection that can act as a hotspot. The procedure is the following: | ||
| - | * Unordered List ItemThe hotspot should be configured with the ssid and the password specified in wpa_supplicant.conf. The raspberry will automatically connect to a network with this configuration. | ||
| - | * As soon as the connection is established, | ||
| - | * In order to make sure that the transaction completed successfully, | ||
medal-hub.1639493044.txt.gz · Last modified: 2021/12/14 15:44 by arnaud_poletto