Installation and startup

The following section provides a comprehensive, step-by-step guide to the installation process for developers, production environments, and users of our compiled public Docker images.

Three options are available for running the HMC FAIR Data Dashboard on your local machine. Although the step-by-step-instructions are given for Linux operating systems, similar ways exist for installing it on Windows and MacOS:

Option 1: Installing the HMC FAIR Data Dashboard as a stand-alone app using Python virtual environments.
Option 2: Installing the HMC FAIR Data Dashboard as a stand-alone app using docker compose.
Option 3: Joint deployment of the HMC Toolbox for Data Mining together with the HMC FAIR Data Dashboard using docker compose.

The installation instructions for all of these options can be found below.

Option 1: Installing the HMC FAIR Data Dashboard as a stand-alone app using Python virtual environments (Linux)

Setup of the development environment

These are the required packages to be in your machine.

 sudo apt install python3-pip python3-venv git

Clone the source code from the GitLab repository

Clone the HMC FAIR Data Dashboard (opens in a new tab) public GitLab repository, by

 git clone https://codebase.helmholtz.cloud/hmc/hmc-public/FAIR-dashboard/hmc-fair-data-dashboard.git

 git clone git@codebase.helmholtz.cloud:hmc/hmc-public/FAIR-dashboard/hmc-fair-data-dashboard.git

Create the virtual environments

cd hmc-fair-data-dashboard    # change to app directory
python3 -m venv venv        # creates a virtual environment in directory 'venv'
source venv/bin/activate    # enables the virtual environment

Install the required packages

using

pip install -e .

A list of all packages required to locally run the dashboard can be found here or in the respective section of the file code.meta in the repository.

Configuration of environment variables

Create .env file and fill it as .env.example

touch .env

or copy the .env.example and then fill it with your desire variable

cp .env.example .env

An example of the environment variable file can be found here.

Make sure the dashboard has access to the database

Create .env file and fill it as .env.example

Make sure the dashboard has access to F-UJI

Access to a F-UJI server (opens in a new tab) is required for running the live-assessment in the dashboard-subpage Assess My Data. If you choose to install the Dashboard via python virtual environments, you should also setup and run the F-UJI Service by your self, (see F-UJI installation instructions (opens in a new tab)).

We provide the setup to run a local F-UJI server using Docker images in parallel to the dashboard in the docker-compose.yml file.

F-UJI (opens in a new tab) is a web service to programmatically assess the performance of digital data objects with respect to specific aspects of the FAIR principles, as based on metrics (opens in a new tab) developed by the FAIRsFAIR (opens in a new tab) project. The service is used to evaluate data publications presented in the dashboard. -- Devaraju, A. and Huber, R. (2021). An automated solution for measuring the progress toward FAIR research data. Patterns, vol 2(11), https://doi.org/10.1016/j.patter.2021.100370` (opens in a new tab)

Run the dashboard

Option A: Run the dashboard locally

To run locally the project, use:

python app.py

Dash is running on http://127.0.0.1:8050/

For further development, you may also exchange app.run_server() with app.run_server(debug=True) in the file app.py.

Option B: Run the dashboard in production mode

The dashboard can be installed on your production server with the same steps by running them in a run.sh file.

You therefore add gunicorn (opens in a new tab) - Gunicorn 'Green Unicorn', a Python WSGI HTTP Server for UNIX. It is a pre-fork model. The Gunicorn server is broadly compatible with various web frameworks, simply implemented, light on server resources, and fairly performant.

./run.sh

💡

Executable permission is required for the run.sh file, and you can achieve it via:

sudo chmod +x run.sh

Option 2: Installing the HMC FAIR Data Dashboard as a stand-alone app using docker compose (Linux)

The dashboard can be run from a docker image available in the GitLab Container Registry (opens in a new tab). This docker image of the most recent release is pulled automatically when deploying locally in the following way.

As described above for Option 1, running the dashboard as a stand-alone app requires access to a F-UJI server and at least a minimum setup of the database using mariadb.

Install docker and docker compose

The HMC FAIR Data Dashboard comes with an easy-to-use Docker container. First you need to install Docker (opens in a new tab) as well as Docker Compose V2 (opens in a new tab).

Clone the source code from the GitLab repository

Clone the HMC FAIR Data Dashboard (opens in a new tab) public GitLab repository, by

 git clone https://codebase.helmholtz.cloud/hmc/hmc-public/FAIR-dashboard/hmc-fair-data-dashboard.git

 git clone git@codebase.helmholtz.cloud:hmc/hmc-public/FAIR-dashboard/hmc-fair-data-dashboard.git

Configuration of environment variables

Change path to the new directory:

cd hmc-fair-data-dashboard

Create .env file and fill it as .env.example

touch .env

or copy the .env.example and then fill it with your desire variables

cp .env.example .env

An example of the environment variable file can be found here.

Run the dashboard using docker compose

docker compose up

Please note: A prerequisite for using the HMC FAIR Data Dashboard is a local instance of the F-UJI Server (opens in a new tab) as well as a preconfigured MariaDB-database. With the instructions given in docker-compose.yml, both the database as well as an instance of the F-UJI Server should be launched in parallel to the HMC FAIR Data Dashboard.

Option 3: Joint deployment of the HMC Toolbox for Data Mining together with the HMC FAIR Data Dashboard using docker compose (Linux)

The following instructions address a joint deployment of the HMC Toolbox for Data Mining together with the HMC FAIR Data Dashboard using docker compose on Linux machines. This allows you to show and explore the data harvested by the HMC Toolbox for Data Mining in the HMC FAIR Data Dashboard. For this purpose, we create another public GitLab repository Production setup HMC Toolbox and HMC Dashboard (opens in a new tab).

Install docker and docker compose

The Production setup HMC Toolbox and HMC Dashboard comes with an easy-to-use Docker container. First you need to install Docker (opens in a new tab) as well as Docker Compose V2 (opens in a new tab).

Clone the source code from the GitLab repository

Clone the Production setup HMC Toolbox and HMC Dashboard (opens in a new tab) public GitLab repository, by

 git clone https://codebase.helmholtz.cloud/hmc/hmc-public/FAIR-dashboard/production-setup-hmc-toolbox-and-hmc-dashboard.git

 git clone git@codebase.helmholtz.cloud:hmc/hmc-public/FAIR-dashboard/production-setup-hmc-toolbox-and-hmc-dashboard.git

Configuration of environment variables

Change path to the new directory:

cd production-setup-hmc-toolbox-and-hmc-dashboard

Create .env file and fill it as .env.example

touch .env

or copy the .env.example and then fill it with your desire variables

cp .env.example .env

An example of the environment variable file can be found here (opens in a new tab).

Run the dashboard using docker compose

docker compose up

Please Note: Upon completion of the pull and create process of the corresponding docker containers, the HMC FAIR Data Dashboard will show you the emply graphs. This is because the database is emplyed in a first step. HMC Toolbox for Data Mining container will harvest the data, enrich it, score it and finally store it in the database.

After finishing the process of HMC Toolbox for Data Mining jobs, HMC FAIR Data Dashboard will have the data to show. (at this stage it is necessary to restart HMC FAIR Data Dashboard)

Overview Modify and add pages