Update instructions for API deployment

Dockerfile

@@ -1,20 +1,24 @@
-FROM ubuntu:20.04
-
-MAINTAINER Fernando Aguilar "[email protected]"
+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"]

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.

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/<plugin_name>/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)

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)

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