medAL-data Setup

Purpose and Scope

This page 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.

Material

You will need the following material:

A Linux server with the following minimal requirements:
- 8GB RAM
- 300GB disk capacity
- Operating System: Ubuntu >= 18.04
A 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/)
A domain Name (In the installation we will use the name example.com) pointing to the server's IP address.

Environment Setup

Firstly, 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

Install Docker

To setup Docker on the remote server, follow this procedure:

[t_remote] To update ubuntu server, type:
```
sudo apt update
```
[t_remote] Install a few prerequisite packages which let apt use packages over HTTPS by typing:
```
sudo apt install apt-transport-https ca-certificates curl software-properties-common
```
[t_remote] Add the GPG key for the official Docker repository to your system by typing:
```
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
```

[t_remote] Add the Docker repository to APT sources:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"

[t_remote] Update the package database with the Docker packages from the newly added repository:
```
sudo apt update
```

[t_remote] Make sure you are about to install from the Docker repository instead of the default Ubuntu repository:

apt-cache policy docker-ce

You will see an output like the following:

docker-ce:
  Installed: (none)
  Candidate: <version-number>
  Version table:
    <version-number> 500
      500 https://download.docker.com/linux/ubuntu bionic/stable amd64 Packages

[t_remote] Finally, install Docker:
```
sudo apt install docker-ce
```
[t_remote] Docker should now be installed, the daemon started, and the process enabled to start on boot. Check that it’s running:
```
sudo systemctl status docker
```

For more information, you can check on this site (https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04)

Install Nginx

To setup Nginx on the remote server, follow these steps:

[t_remote] Install nginx:
```
sudo apt install nginx
```
[t_remote] Enable nginx in the firewall by typing:
```
sudo ufw allow 'Nginx Full'
```

Install Dokku

To setup Dokku on the remote server, follow these steps:

[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/
[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:
[t_local] 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
```
[t_local] Enter your domain name example.com in the corresponding dialog box.

Application Deployment

Now, deploy your application by following this procedure:

[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

[t_local] On the local workstation, clone the source code of the medal-data server from the bitbucket repository:
```
git clone https://informatique_unisante@bitbucket.org/wavemind_swiss/liwi-main-data.git
```
, and navigate to the project folder:
```
cd liwi-main-data 
```
[t_local] Do a copy the .env.dokku.example file and name it .env.dokku:
```
cp .env.dokku.example .env.dokku 
```
and fill out the values depending on your desired configuration:
```
sudo nano .env.dokku 
```
You can find an exhaustive list of environment variables here. Contact an administrator if you are not sure about any variable in this file.
[t_remote] 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):
```
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/).

[t_remote] Back on the remote server, run the following command to set the APP_KEY environment variable:

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:
```
dokku run medal-data php artisan passport:keys
```
Make sure that to setup the ther environment variables properly in your .env file. You can find an exhaustive list of environment variables here.

Refresh the configuration:

dokku run medal-data php artisan config:cache

[t_remote] Finally, migrate and seed the database using:

dokku run medal-data php artisan migrate:fresh --seed --force

[t_remote] medAL-data automatically implements a Two-factor authentication strategy. Run the following command to generate 2FA codes:
```
dokku run medal-data php artisan 2fa:authenticate_all
```
and confirm by typing yes. For more information about Two-factor authentication, click here.

[t_remote] If you need to export existing data from medal-creator, run:
```
dokku run medal-data php artisan medalc:retrieve_data
```

Domain Setup

[t_remote] On your server terminal, set domain:
```
sudo dokku domains:set medal-data <domain>
```
where domain is the domain for medAL-data.

Setting up letsencrypt with Dokku

[t_remote] On your server terminal, install letsencrypt plugin with:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

[t_remote] Install certificate with

sudo dokku letsencrypt:enable medal-data

[t_remote] Restart the server:
```
sudo dokku ps:restart medal-data
```
Open your browser and test the system. Make sure to setup the Two-factor authentication before logging in. You should be able to login with the admin credentials using the email address admin@dynamic.com. Contact an administrator to know the default admin password.

medAL-suite documentation

Table of Contents