From 1039f79b4970e7015bc94ff501d196917e143481 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Tue, 14 Jan 2025 14:47:52 +0100 Subject: [PATCH] Update sphinx based docs refs: #117 EOEPCA/roadmap#264 --- README.md | 5 ++-- docs/pages/configuration.md | 51 ++++++++++++++++++++++++++++++++----- docs/pages/installation.md | 15 +++++------ docs/pages/usage.md | 50 ++++++++++++++++++++++++++++++------ 4 files changed, 96 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index c9b49eb..0fde980 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,10 @@ The [docker](docker) folder has a `Dockerfile` to build a Docker image, e.g.: docker build -t openeo-aggregator -f docker/Dockerfile . -This image is built and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator` +This image is built automatically and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator` The image runs the app in gunicorn by default (serving on `127.0.0.1:8000`). + Example usage, with some extra gunicorn settings and the built-in dummy config: docker run \ @@ -79,7 +80,7 @@ Example usage, with some extra gunicorn settings and the built-in dummy config: -e OPENEO_BACKEND_CONFIG=/home/openeo/venv/lib/python3.11/site-packages/openeo_aggregator/config/examples/aggregator.dummy.py \ vito-docker.artifactory.vgt.vito.be/openeo-aggregator:latest -The webapp should be available at http://localhost:8080/openeo/1.2 +This webapp should be available at http://localhost:8080/openeo/1.2 ## Further configuration diff --git a/docs/pages/configuration.md b/docs/pages/configuration.md index e76bd63..cc7fb77 100644 --- a/docs/pages/configuration.md +++ b/docs/pages/configuration.md @@ -1,15 +1,52 @@ +# Configuration +## Essential configuration -# Configuration +The openEO-Aggregator specific configuration, +is grouped by an `AggregatorBackendConfig` container object +(subclass of `OpenEoBackendConfig` as defined in the `openeo-python-driver` framework project). + +The most important config value is `aggregator_backends`, which +defines the backends to "aggregate". +See [`src/openeo_aggregator/config/config.py`](https://github.com/Open-EO/openeo-aggregator/blob/master/src/openeo_aggregator/config/config.py) +for more details and other available configuration options. + +Use the env var `OPENEO_BACKEND_CONFIG` to point to the desired config path. +For example, using the example [dummy config](https://github.com/Open-EO/openeo-aggregator/blob/master/src/openeo_aggregator/config/examples/aggregator.dummy.py) +from the repo: + +```shell +export OPENEO_BACKEND_CONFIG=src/openeo_aggregator/config/examples/aggregator.dummy.py +``` + + +When no valid openEO-Aggregator is set that way, you typically get this error: + +```text +ConfigException: Expected AggregatorBackendConfig but got OpenEoBackendConfig +``` + + +## Further configuration + +The flask/gunicorn related configuration can be set through +standard flask/gunicorn configuration means +like command line options or env variables, as shown above. -:::{Attention} -This documentation page is work in progress... 👷 -::: +### Gunicorn config +For running with gunicorn, there is an example config at `src/openeo_aggregator/config/examples/gunicorn-config.py`, +for example to be used like this: -The openEO Aggregator can be configured through a `AggregatorBackendConfig` class +```shell +gunicorn --config=src/openeo_aggregator/config/examples/gunicorn-config.py 'openeo_aggregator.app:create_app()' +``` +### Logging -## Gunicorn configuration +By default, logging is done in JSON format. +You can switch to a simple text-based logging with this env var: -TODO +```shell +OPENEO_AGGREGATOR_SIMPLE_LOGGING=1 +``` diff --git a/docs/pages/installation.md b/docs/pages/installation.md index d9999cf..7b19d8a 100644 --- a/docs/pages/installation.md +++ b/docs/pages/installation.md @@ -1,17 +1,16 @@ - # Installation -:::{Attention} -This documentation page is work in progress... 👷 -::: - - -The openEO Aggregator can be installed via pip: +The openEO Aggregator is a Python package and can be installed via standard tooling like `pip`. +While it's possible to install it with a naive `pip install openeo-aggregator`, +the current build workflows push the related packages to a dedicated repository (instead of PyPI), +so to install a recent version it is generally recommended to install with ```shell -python -m pip install openeo-aggregator +python -m pip install openeo-aggregator --extra-index-url https://artifactory.vgt.vito.be/api/pypi/python-openeo/simple ``` +At the time of this writing it is recommended to work with Python 3.11. + ## Requirements diff --git a/docs/pages/usage.md b/docs/pages/usage.md index 74b2ffa..df9010a 100644 --- a/docs/pages/usage.md +++ b/docs/pages/usage.md @@ -1,21 +1,55 @@ +# Running the aggregator -# Usage -:::{Attention} -This documentation page is work in progress... 👷 -::: +Note: make sure you [point to a valid configuration file](configuration.md) +before trying to run the web app. -## Run with Flask in development mode +### Flask dev mode + +To run locally in development mode, with standard Flask workflow, +for example (also see `./scripts/run-flask-dev.sh`): ```shell -export FLASK_APP='openeo_aggregator.app:create_app()' +export FLASK_APP=openeo_aggregator.app export FLASK_ENV=development flask run ``` -## Run with Gunicorn +The webapp should be available at http://localhost:5000/openeo/1.2 + + +### With gunicorn + +To run the app as gunicorn application, with desired options, +for example (also see `./scripts/run-gunicorn.sh`): + +```shell +gunicorn --workers=4 --bind 0.0.0.0:8080 'openeo_aggregator.app:create_app()' +``` + +The webapp should be available at http://localhost:8080/openeo/1.2 + + +## Docker image + +The [docker](docker) folder has a `Dockerfile` to build a Docker image, e.g.: ```shell -gunicorn 'openeo_aggregator.app:create_app()' +docker build -t openeo-aggregator -f docker/Dockerfile . ``` + +This image is built automatically and hosted by VITO at `vito-docker.artifactory.vgt.vito.be/openeo-aggregator` + +The image runs the app in gunicorn by default (serving on `127.0.0.1:8000`). + +Example usage, with some extra gunicorn settings and the built-in dummy config: + + docker run \ + --rm \ + -p 8080:8080 \ + -e GUNICORN_CMD_ARGS='--bind=0.0.0.0:8080 --workers=2' \ + -e OPENEO_BACKEND_CONFIG=/home/openeo/venv/lib/python3.11/site-packages/openeo_aggregator/config/examples/aggregator.dummy.py \ + vito-docker.artifactory.vgt.vito.be/openeo-aggregator:latest + +This webapp should be available at http://localhost:8080/openeo/1.2