Authors

Stefano Valentini https://github.com/valent0ne
Valentina Cecchini https://github.com/Nimerya

Introduction

Many melanoma observational studies have been carried out across different countries and geographic areas using heterogeneous assessments of epidemiologic risk factors and clinical variables.
The aim is to develop a consensus questionnaire to standardize epidemiologic and clinical data collection for melanoma risk assessment.
Melanoq is the product of the work of the MelanoStrum Consortium.

This project's goal is to implement a digital version of the aforementioned questionnaire by providing a way to compile the questionnaire itself and to expose the physicians, researchers and authorized personnel a way to query the data stored in the questionnaires' database.

Deployment

Requirements

CouchBase Server - https://www.couchbase.com/
Apache Tomcat - http://tomcat.apache.org/
Apache Maven - https://maven.apache.org/
Yarn - https://yarnpkg.com/en/ or NPM (Node Package Manager) - https://www.npmjs.com/
VueJS CLI - https://cli.vuejs.org/

Database

Download and install CouchBase Server Community or Enterprise from here: https://www.couchbase.com/downloads.

After having installed and run it, its web interface will be available at the address http://machine-ip:8091, configure the server according to your preferences and then create a user and a bucket (remember that the bucket name and the user's credentials must then be provided to the MelanoQ api server), finally add all the permissions to the created user for the created bucket.

Go to the Query section of the web interface and run:

CREATE PRIMARY INDEX ON bucketname USING VIEW;

where bucketname is the name of the created bucket.

Now the database is empty, so you need to manually add an admin user for the MelanoQ api server:

generate a bcrypt password from this online tool: https://www.browserling.com/tools/bcrypt using 12 rounds (be sure to check that the generated encrypted password starts with the $2a prefix)

execute the following query:

INSERT INTO bucketname (KEY, VALUE) 
 VALUES 
 (
    "k999", 
    {
        "role": "admin", 
        "username": "name", 
        "password": "generated-password", 
        "_class": "it.univaq.disim.bioinformatics.melanoq.model.User"
     }
 )

where k999 is any random alphanumeric string, name is a name of your choice and generated-password is the bcrypt password you previously generated.

If you need to backup the database content run:

> cbbackup http://machine-ip:8091 path-to-dest-folder -u username -p password -b bucket-name

if you need to restore a backup run:

> cbrestore path-to-source-folder http://machine-ip:8091 -u username -p password -b bucket-name -x rehash=1

where cbbackup and cbrestore are tools that are located in the installation directory of CouchBase Server.

Server

> git clone https://gitlab.com/valent0ne/melanoq.git 
> cd ./melanoq/code/api 
> mvn clean package

Now inside the directory ./melanoq/code/api/target/ there will be a file named melanoq-x.y.z.jar, move this file inside your Apache Tomcat webapp directory.
The MelanoQ api server will be available at the address http://machine-ip:8080/melanoq/api. To change the application parameters (e.g., couchbase server credentials and address), before executing the command mvn clean package edit the file application.properties located in the directory ./melanoq/code/api/src/main/resources.

Webclient

> git clone https://gitlab.com/valent0ne/melanoq.git
> cd ./melanoq/code/webclient
> yarn
> yarn build

or (if you are using npm instead of yarn):

> git clone https://gitlab.com/valent0ne/melanoq.git
> cd ./melanoq/code/webclient
> npm
> npm run build

Before executing the build command, remember to edit the config.js file inside the directory ./melanoq/code/webclient/src/common with the correct ip address of the MelanoQ api server.

Now you have two options:

double-click index.html inside the directory ./melanoq/code/webclient/dist to directly access the local instance of the client
deploy the client (copy the content of the directory ./melanoq/code/webclient/dist) into an http server (Apache Tomcat or others) to expose the client to the public.