Skip to content

Commit

Permalink
Furhter update sphinx based docs
Browse files Browse the repository at this point in the history
  • Loading branch information
soxofaan committed Jan 14, 2025
1 parent 1039f79 commit c3cfd2d
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 14 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ from the repo:

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:
When no valid openEO-Aggregator configuration is set that way, you typically get this error:

ConfigException: Expected AggregatorBackendConfig but got OpenEoBackendConfig

Expand Down Expand Up @@ -101,7 +101,7 @@ for example to be used like this:
By default, logging is done in JSON format.
You can switch to a simple text-based logging with this env var:

OPENEO_AGGREGATOR_SIMPLE_LOGGING=1
export OPENEO_AGGREGATOR_SIMPLE_LOGGING=1

## Running tests

Expand Down
26 changes: 21 additions & 5 deletions docs/pages/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,24 @@

The openEO-Aggregator specific configuration,
is grouped by an `AggregatorBackendConfig` container object
(subclass of `OpenEoBackendConfig` as defined in the `openeo-python-driver` framework project).
(subclass of [`OpenEoBackendConfig`](https://github.com/Open-EO/openeo-python-driver/blob/master/openeo_driver/config/config.py)
as defined in the [`openeo-python-driver`](https://github.com/Open-EO/openeo-python-driver) framework project).

The most important config value is `aggregator_backends`, which
defines the backends to "aggregate".

```python
config = AggregatorBackendConfig(
...,
aggregator_backends={
"dummy": "https://openeo.example/",
},
...
)
```



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.

Expand All @@ -20,7 +34,7 @@ export OPENEO_BACKEND_CONFIG=src/openeo_aggregator/config/examples/aggregator.du
```


When no valid openEO-Aggregator is set that way, you typically get this error:
When no valid openEO-Aggregator configuration is set that way, you typically get this error:

```text
ConfigException: Expected AggregatorBackendConfig but got OpenEoBackendConfig
Expand All @@ -31,15 +45,17 @@ ConfigException: Expected AggregatorBackendConfig but got OpenEoBackendConfig

The flask/gunicorn related configuration can be set through
standard flask/gunicorn configuration means
like command line options or env variables, as shown above.
like command line options or env variables, as shown in the [usage docs](usage.md).

### 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:

```shell
gunicorn --config=src/openeo_aggregator/config/examples/gunicorn-config.py 'openeo_aggregator.app:create_app()'
gunicorn \
--config=src/openeo_aggregator/config/examples/gunicorn-config.py \
'openeo_aggregator.app:create_app()'
```

### Logging
Expand All @@ -48,5 +64,5 @@ By default, logging is done in JSON format.
You can switch to a simple text-based logging with this env var:

```shell
OPENEO_AGGREGATOR_SIMPLE_LOGGING=1
export OPENEO_AGGREGATOR_SIMPLE_LOGGING=1
```
24 changes: 22 additions & 2 deletions docs/pages/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,32 @@ the current build workflows push the related packages to a dedicated repository
so to install a recent version it is generally recommended to install with

```shell
python -m pip install openeo-aggregator --extra-index-url https://artifactory.vgt.vito.be/api/pypi/python-openeo/simple
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.
At the time of this writing it is recommended to work with Python 3.11
(as done in the Docker image used in various production deployments).


## Installation from source

If desired, it is also possible to install from source.
As usual, run something like this from the project root in some kind of virtual environment:

```shell
pip install .
```

When planning to do development, it is recommended to install it in development mode (option `-e`) with the `dev` "extra":

```shell
pip install -e .[dev]
```


## Requirements

Some (optional) features have some additional requirements:

- Optional: a Zookeeper cluster for caching and partitioned job db
12 changes: 7 additions & 5 deletions docs/pages/usage.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Running the aggregator
# Usage

How to run the aggregator (flask based) webapp?


Note: make sure you [point to a valid configuration file](configuration.md)
Expand All @@ -16,7 +18,7 @@ export FLASK_ENV=development
flask run
```

The webapp should be available at http://localhost:5000/openeo/1.2
The webapp should be available at [http://localhost:5000/openeo/1.2](http://localhost:5000/openeo/1.2).


### With gunicorn
Expand All @@ -28,12 +30,12 @@ for example (also see `./scripts/run-gunicorn.sh`):
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
The webapp should be available at [http://localhost:8080/openeo/1.2](http://localhost:8080/openeo/1.2).


## Docker image

The [docker](docker) folder has a `Dockerfile` to build a Docker image, e.g.:
The [docker](https://github.com/Open-EO/openeo-aggregator/blob/master/docker) folder has a `Dockerfile` to build a Docker image, e.g.:

```shell
docker build -t openeo-aggregator -f docker/Dockerfile .
Expand All @@ -52,4 +54,4 @@ 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

This webapp should be available at http://localhost:8080/openeo/1.2
This webapp should be available at [http://localhost:8080/openeo/1.2](http://localhost:8080/openeo/1.2).

0 comments on commit c3cfd2d

Please sign in to comment.