From a16743c2d67bad9dcf6d48783d47ee6f578e711a Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Wed, 10 Dec 2025 08:04:42 +0100 Subject: [PATCH 1/9] Input argument for host IP to run the API server (defaults to localhost) --- fair_eva/__init__.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/fair_eva/__init__.py b/fair_eva/__init__.py index 8931c99..3fe84f1 100755 --- a/fair_eva/__init__.py +++ b/fair_eva/__init__.py @@ -9,6 +9,14 @@ def set_parser(): parser = argparse.ArgumentParser(description="FAIR EVA API server") + parser.add_argument( + "--host", + type=str, + metavar="HOST", + dest="host", + default="127.0.0.1", + help="Host IP where API server will run (default: 127.0.0.1)", + ) parser.add_argument( "-p", "--port", @@ -31,4 +39,4 @@ def main(): arguments={"title": "FAIR evaluator"}, resolver=RestyResolver("fair_eva.api"), ) - app.run(port=options_cli.port) + app.run(host=options_cli.host, port=options_cli.port) \ No newline at end of file From f189496bc296ed47c0bccdedcd233f6272b421ad Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Tue, 16 Dec 2025 10:35:10 +0100 Subject: [PATCH 2/9] Modify Dockerfile for handling new input arguments --- Dockerfile | 28 +++++++++++++++------------- scripts/entrypoint.sh | 16 ++++++++++++++++ 2 files changed, 31 insertions(+), 13 deletions(-) create mode 100644 scripts/entrypoint.sh diff --git a/Dockerfile b/Dockerfile index 354b358..42b9af1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,20 +1,22 @@ -FROM ubuntu:20.04 - -MAINTAINER Fernando Aguilar "aguilarf@ifca.unican.es" +FROM python:3.11-slim AS base RUN apt-get update -y && \ apt-get install -y curl python3-pip python3-dev git vim lsof -RUN git clone https://github.com/ifca-advanced-computing/FAIR_eva.git - +COPY . /FAIR_eva WORKDIR /FAIR_eva - +RUN chmod +x scripts/entrypoint.sh +RUN pip3 install git+https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh RUN pip3 install -r requirements.txt +RUN pip3 install . + +ARG FAIR_EVA_HOST=0.0.0.0 +ARG FAIR_EVA_PORT=9090 +ARG START_CMD="fair-eva" + +ENV FAIR_EVA_HOST=${FAIR_EVA_HOST} \ + FAIR_EVA_PORT=${FAIR_EVA_PORT} \ + START_CMD=${START_CMD} -EXPOSE 5000 9090 -RUN ls -RUN mv /FAIR_eva/config.ini.template /FAIR_eva/config.ini -RUN cd /FAIR_eva -RUN chmod 777 start.sh -RUN cat start.sh -CMD /FAIR_eva/start.sh +EXPOSE ${FAIR_EVA_PORT} +ENTRYPOINT ["/FAIR_eva/scripts/entrypoint.sh"] \ No newline at end of file diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh new file mode 100644 index 0000000..032d5f1 --- /dev/null +++ b/scripts/entrypoint.sh @@ -0,0 +1,16 @@ +#!/bin/bash + +# Entrypoint script for FAIR_eva Docker container +# This script handles environment variables and launches the fair-eva application + +# Set default values for environment variables +FAIR_EVA_HOST=${FAIR_EVA_HOST:-0.0.0.0} +FAIR_EVA_PORT=${FAIR_EVA_PORT:-9090} +START_CMD=${START_CMD:-fair-eva} + +# Build the command to run fair-eva +CMD="$START_CMD --host $FAIR_EVA_HOST --port $FAIR_EVA_PORT" + +# Execute the command +echo "Starting FAIR_eva with command: $CMD" +exec $CMD \ No newline at end of file From 0042e8e7465ad8099fcd52c39ee832c72ea9b2fc Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Tue, 16 Dec 2025 11:07:59 +0100 Subject: [PATCH 3/9] Fix style --- Dockerfile | 2 +- scripts/entrypoint.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 42b9af1..e22b8af 100644 --- a/Dockerfile +++ b/Dockerfile @@ -19,4 +19,4 @@ ENV FAIR_EVA_HOST=${FAIR_EVA_HOST} \ START_CMD=${START_CMD} EXPOSE ${FAIR_EVA_PORT} -ENTRYPOINT ["/FAIR_eva/scripts/entrypoint.sh"] \ No newline at end of file +ENTRYPOINT ["/FAIR_eva/scripts/entrypoint.sh"] diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh index 032d5f1..7fbfe49 100644 --- a/scripts/entrypoint.sh +++ b/scripts/entrypoint.sh @@ -13,4 +13,4 @@ CMD="$START_CMD --host $FAIR_EVA_HOST --port $FAIR_EVA_PORT" # Execute the command echo "Starting FAIR_eva with command: $CMD" -exec $CMD \ No newline at end of file +exec $CMD From f9fc79467fa0d92693a333fd6b155136b6b2a088 Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Tue, 16 Dec 2025 12:05:14 +0100 Subject: [PATCH 4/9] Enable/disable debug through --debug option --- Dockerfile | 2 ++ fair_eva/__init__.py | 14 +++++++++++++- scripts/entrypoint.sh | 7 +++++++ 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index e22b8af..3c2e7be 100644 --- a/Dockerfile +++ b/Dockerfile @@ -12,10 +12,12 @@ RUN pip3 install . ARG FAIR_EVA_HOST=0.0.0.0 ARG FAIR_EVA_PORT=9090 +ARG FAIR_EVA_LOGLEVEL=info ARG START_CMD="fair-eva" ENV FAIR_EVA_HOST=${FAIR_EVA_HOST} \ FAIR_EVA_PORT=${FAIR_EVA_PORT} \ + FAIR_EVA_LOGLEVEL=${FAIR_EVA_LOGLEVEL} \ START_CMD=${START_CMD} EXPOSE ${FAIR_EVA_PORT} diff --git a/fair_eva/__init__.py b/fair_eva/__init__.py index 3fe84f1..86ce03e 100755 --- a/fair_eva/__init__.py +++ b/fair_eva/__init__.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 import argparse +import logging import connexion from connexion.resolver import RestyResolver @@ -26,6 +27,15 @@ def set_parser(): default=9090, help="Port number where API server will run (default: 9090)", ) + parser.add_argument( + "-d", + "--debug", + help="Enable debugging", + action="store_const", + dest="log_level", + const=logging.DEBUG, + default=logging.INFO, + ) return parser.parse_args() @@ -39,4 +49,6 @@ def main(): arguments={"title": "FAIR evaluator"}, resolver=RestyResolver("fair_eva.api"), ) - app.run(host=options_cli.host, port=options_cli.port) \ No newline at end of file + logger = logging.getLogger("api") + logger.info("Starting FAIR EVA API server...") + app.run(host=options_cli.host, port=options_cli.port) diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh index 7fbfe49..308e1fc 100644 --- a/scripts/entrypoint.sh +++ b/scripts/entrypoint.sh @@ -6,11 +6,18 @@ # Set default values for environment variables FAIR_EVA_HOST=${FAIR_EVA_HOST:-0.0.0.0} FAIR_EVA_PORT=${FAIR_EVA_PORT:-9090} +FAIR_EVA_LOGLEVEL=${FAIR_EVA_LOGLEVEL:-info} START_CMD=${START_CMD:-fair-eva} # Build the command to run fair-eva CMD="$START_CMD --host $FAIR_EVA_HOST --port $FAIR_EVA_PORT" +# Transform FAIR_EVA_LOGLEVEL to boolean for --debug flag +# If FAIR_EVA_LOGLEVEL is set to "debug", enable the --debug option +if [ "$FAIR_EVA_LOGLEVEL" = "debug" ]; then + CMD="$CMD --debug" +fi + # Execute the command echo "Starting FAIR_eva with command: $CMD" exec $CMD From 6653a6f7d238aa1276aa2202f9d94b839ef7913c Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Tue, 16 Dec 2025 14:02:46 +0100 Subject: [PATCH 5/9] Minor fix --- README.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3e65534..33c6d1d 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,27 @@ Aguilar Gómez, F., Bernal, I. FAIR EVA: Bringing institutional multidisciplinary repositories into the FAIR picture. Sci Data 10, 764 (2023). https://doi.org/10.1038/s41597-023-02652-8 ## Quickstart +To deploy an [OAI-PMH ready](https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh) FAIR EVA API server using Docker: +```bash +# Build docker image locally (from the repository root path) +docker build -t fair-eva-api . + +# Run FAIR EVA API (using the previously built image) +docker run --rm -d --network host --name fair_eva_api fair-eva-api ``` -docker run --name=fair_eva -p 9090:9090 -p 5000:5000 -dit --network host + +### Trigger the FAIR data assessement +Once the API is up, FAIR data assessment can be exercised. Check [the examples from the documentation](./docs/usage.md#perform-an-evaluation) for working examples. + +### Gathering evaluation logs from FAIR EVA API container +FAIR EVA API logs are accessible with the following Docker command. Ensure to execute this command **before** triggering the evaluation: + +```bash +# Use `--follow` option for interactive logging +docker logs --follow fair_eva_api ``` # Acknowledgements -This software started to be developed within IFCA-Advanced-Computing receives -funding from the European Union’s Horizon 2020 research and -innovation programme under grant agreement No 857647. +This software has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 857647. From b0d677fdd5a42233a9881afbee0a48e06693278f Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Tue, 16 Dec 2025 14:03:06 +0100 Subject: [PATCH 6/9] Improve installation and usage --- docs/installation.md | 87 ++++++++++++++++++++++++++++++++------------ 1 file changed, 63 insertions(+), 24 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 7fbdc0e..072234f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,55 +1,94 @@ -# Installation +# API deployment -FAIR EVA can be run locally via Python or containerised with Docker. For development, clone the repository: +The FAIR EVA API can be deployed locally via Python or through a Docker container. + +## Python-way + +FAIR EVA requires Python 3.9 or later. It is recommended to create a virtual environment: ```bash -git clone https://github.com/IFCA-Advanced-Computing/FAIR_eva.git -cd FAIR_eva -pip install . +python3 -m venv venv +source venv/bin/activate +(venv) pip install git+https://github.com/IFCA-Advanced-Computing/FAIR_eva ``` -Then you can run FAIR EVA launching the appplication, by default listening in port 9090: + +This will install the API server alone which provides basic functionality. In order to fully explore the capabilities of the FAIR evaluator, a FAIR EVA plugin shall be installed as well. The [OAI-PMH plugin](https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh) integrates with a wide range of data repositories: + +```bash +(venv) pip install git+https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh +``` + +### Launch the API +Once installed, the `fair-eva` executable is available in the system and can be launched just by running the command (by default listens on port 9090): ```bash fair-eva ``` -## Using Python +Further customisation can be achieved through the available options: -FAIR EVA requires Python 3.9 or later. It is recommended to create a virtual environment: +```bash +$ fair-eva --help +usage: fair-eva [-h] [--host HOST] [-p PORT] [-d] + +FAIR EVA API server + +options: + -h, --help show this help message and exit + --host HOST Host IP where API server will run (default: 127.0.0.1) + -p, --port PORT Port number where API server will run (default: 9090) + -d, --debug Enable debugging +``` + +## Docker-way +An easy way to run FAIR EVA API is through a Docker container. The repository includes a [`Dockerfile`](./Dockerfile) that compiles the steps to deploy the application. First, the container image needds to be built: ```bash -python3 -m venv venv -source venv/bin/activate -pip install --upgrade pip +# Build docker image locally (from the repository root path) +docker build -t fair-eva-api . ``` -Install the required dependencies: +This will create the `fair-eva-api:latest` Docker image. + +### Launch the API +Use the following Docker command to launch the API: ```bash -pip install -r requirements.txt +docker run --rm -d --network host --name fair_eva_api fair-eva-api:latest ``` -Some optional features (e.g., PDF generation or translations) may require additional packages listed in `test-requirements.txt`. +The options at runtime can be customised through the following environment variables: + +| FAIR EVA variable | Default value | +|------------------------|---------------| +| FAIR_EVA_HOST | 0.0.0.0 | +| FAIR_EVA_PORT | 9090 | +| FAIR_EVA_LOGLEVEL | info | -## Using Docker -An easier way to run FAIR EVA is through Docker. The repository includes a `Dockerfile` that sets up the environment. To build and run the image: +# Development + ```bash -docker build -t fair_eva . -docker run --name=fair_eva \ - -p 9090:9090 -dit \ - fair_eva +git clone https://github.com/IFCA-Advanced-Computing/FAIR_eva.git +cd FAIR_eva +pip install -r requirements.txt +pip install . ``` -The container exposes two ports: 9090 for the REST API. Once the container is running, you cna run tests requesting HTTP to `http://localhost:9090` in your browser to access the evaluation dashboard. +Follow the installation steps for and install the required dependencies: -## Web client -Older versions of FAIR EVA integrated API and Web client in the same repository. In this version, a new web client can be found in a separated repo. [Web Client](https://github.com/IFCA-Advanced-Computing/fair_eva_web_client) +```bash +pip install -r requirements.txt # application +pip install -r test-requirements.txt # PDF generation,translations +``` -## Configuration files +# Configuration files FAIR EVA reads configuration parameters from INI files. When running the evaluator, two files are loaded: 1. **Global configuration** – typically named `config.ini` or derived from `config.ini.template` in the project root. It defines generic terms, supported vocabularies and repository mappings. 2. **Plugin configuration** – located at `plugins//config.ini` (in each plugin repo). It customises the tests for a specific repository. For example, the **GBIF** plugin defines which metadata fields correspond to identifiers, licences, access protocols and controlled vocabularies. + +# Web client +Older versions of FAIR EVA integrated API and Web client in the same repository. In this version, a new web client can be found in a separated repo. [Web Client](https://github.com/IFCA-Advanced-Computing/fair_eva_web_client) \ No newline at end of file From b4746691afa614b53ab85870b49bbc77777ee296 Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Thu, 18 Dec 2025 10:28:23 +0100 Subject: [PATCH 7/9] Options to deploy and execute the API server --- docs/installation.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index 072234f..ebede3e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -57,7 +57,9 @@ Use the following Docker command to launch the API: docker run --rm -d --network host --name fair_eva_api fair-eva-api:latest ``` -The options at runtime can be customised through the following environment variables: +### API server customisation + +The API server can be customised both at build and runtime, currently constrained to the following environment variables: | FAIR EVA variable | Default value | |------------------------|---------------| @@ -65,6 +67,15 @@ The options at runtime can be customised through the following environment varia | FAIR_EVA_PORT | 9090 | | FAIR_EVA_LOGLEVEL | info | +- At build time, these variables can be passed with the `--build-arg` option. For instance, the following build command will set the default API port to 9099: +```bash +docker build --build-arg FAIR_EVA_PORT=9099 -t fair-eva-api . +``` + +- At runtime, the default variables can be overriden: +```bash +docker run --rm -d --network host --name fair_eva_api -e FAIR_EVA_PORT=9091 fair-eva-api:latest +``` # Development From e4f76107e3e5cc3beda7f17a22b19dd43fa10ffc Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Thu, 18 Dec 2025 11:30:04 +0100 Subject: [PATCH 8/9] Docker deployment as quickstart and links to docs --- README.md | 4 +++- docs/installation.md | 19 ++++--------------- 2 files changed, 7 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 33c6d1d..2f08560 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Aguilar Gómez, F., Bernal, I. FAIR EVA: Bringing institutional multidisciplinary repositories into the FAIR picture. Sci Data 10, 764 (2023). https://doi.org/10.1038/s41597-023-02652-8 ## Quickstart -To deploy an [OAI-PMH ready](https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh) FAIR EVA API server using Docker: +The quickest way to deploy FAIR EVA API server is using Docker: ```bash # Build docker image locally (from the repository root path) @@ -27,6 +27,8 @@ docker build -t fair-eva-api . docker run --rm -d --network host --name fair_eva_api fair-eva-api ``` +By default the docker image deploys an [OAI-PMH ready](https://github.com/IFCA-Advanced-Computing/fair-eva-plugin-oai-pmh) FAIR EVA API server, which will listen on port 9090. Further details can be found in the [docs](docs/installation.md). + ### Trigger the FAIR data assessement Once the API is up, FAIR data assessment can be exercised. Check [the examples from the documentation](./docs/usage.md#perform-an-evaluation) for working examples. diff --git a/docs/installation.md b/docs/installation.md index ebede3e..4e1f167 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,6 +1,6 @@ # API deployment -The FAIR EVA API can be deployed locally via Python or through a Docker container. +FAIR EVA API can be deployed locally via Python or through a Docker container. ## Python-way @@ -19,7 +19,7 @@ This will install the API server alone which provides basic functionality. In or ``` ### Launch the API -Once installed, the `fair-eva` executable is available in the system and can be launched just by running the command (by default listens on port 9090): +Just type and run the following command (by default listens on port 9090): ```bash fair-eva @@ -78,24 +78,13 @@ docker run --rm -d --network host --name fair_eva_api -e FAIR_EVA_PORT=9091 fair ``` # Development - - -```bash -git clone https://github.com/IFCA-Advanced-Computing/FAIR_eva.git -cd FAIR_eva -pip install -r requirements.txt -pip install . -``` - -Follow the installation steps for and install the required dependencies: +We recommend to follow the Python-way deployment, making sure to install the dependencies for development (`test-requirements.txt`): ```bash -pip install -r requirements.txt # application -pip install -r test-requirements.txt # PDF generation,translations +(venv) pip install -r test-requirements.txt ``` # Configuration files - FAIR EVA reads configuration parameters from INI files. When running the evaluator, two files are loaded: 1. **Global configuration** – typically named `config.ini` or derived from `config.ini.template` in the project root. It defines generic terms, supported vocabularies and repository mappings. From dc180ae72aaa593d4e762d5038681b89c34c89c8 Mon Sep 17 00:00:00 2001 From: Pablo Orviz Date: Thu, 18 Dec 2025 12:39:05 +0100 Subject: [PATCH 9/9] Fix syntax --- docs/installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 4e1f167..203c0cd 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -57,7 +57,7 @@ Use the following Docker command to launch the API: docker run --rm -d --network host --name fair_eva_api fair-eva-api:latest ``` -### API server customisation +### API server customisation The API server can be customised both at build and runtime, currently constrained to the following environment variables: @@ -91,4 +91,4 @@ FAIR EVA reads configuration parameters from INI files. When running the evalu 2. **Plugin configuration** – located at `plugins//config.ini` (in each plugin repo). It customises the tests for a specific repository. For example, the **GBIF** plugin defines which metadata fields correspond to identifiers, licences, access protocols and controlled vocabularies. # Web client -Older versions of FAIR EVA integrated API and Web client in the same repository. In this version, a new web client can be found in a separated repo. [Web Client](https://github.com/IFCA-Advanced-Computing/fair_eva_web_client) \ No newline at end of file +Older versions of FAIR EVA integrated API and Web client in the same repository. In this version, a new web client can be found in a separated repo. [Web Client](https://github.com/IFCA-Advanced-Computing/fair_eva_web_client)