diff --git a/Dockerfile b/Dockerfile index 354b358..3c2e7be 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,20 +1,24 @@ -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 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 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"] diff --git a/README.md b/README.md index 3e65534..2f08560 100644 --- a/README.md +++ b/README.md @@ -17,13 +17,29 @@ 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 +The quickest way to deploy FAIR EVA API server is 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 + +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. + +### 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. diff --git a/docs/installation.md b/docs/installation.md index 7fbdc0e..203c0cd 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: +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 +Just type and run the following 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`. +### API server customisation -## Using Docker +The API server can be customised both at build and runtime, currently constrained to the following environment variables: -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: +| FAIR EVA variable | Default value | +|------------------------|---------------| +| FAIR_EVA_HOST | 0.0.0.0 | +| 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 -t fair_eva . -docker run --name=fair_eva \ - -p 9090:9090 -dit \ - fair_eva +docker build --build-arg FAIR_EVA_PORT=9099 -t fair-eva-api . ``` -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. +- 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 +``` -## 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) +# Development +We recommend to follow the Python-way deployment, making sure to install the dependencies for development (`test-requirements.txt`): -## Configuration files +```bash +(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. 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) diff --git a/fair_eva/__init__.py b/fair_eva/__init__.py index 8931c99..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 @@ -9,6 +10,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", @@ -18,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() @@ -31,4 +49,6 @@ def main(): arguments={"title": "FAIR evaluator"}, resolver=RestyResolver("fair_eva.api"), ) - app.run(port=options_cli.port) + 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 new file mode 100644 index 0000000..308e1fc --- /dev/null +++ b/scripts/entrypoint.sh @@ -0,0 +1,23 @@ +#!/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} +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