diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 738066d2f..f3297a18e 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1,4 +1,5 @@ .. _configuration: +.. include:: references.rst ****************** Configuration @@ -15,10 +16,114 @@ Configuration Settings ======================================= All settings are configured using a ``weaver.ini`` configuration file. A `weaver.ini.example`_ file is provided -with default values to help in the configuration process. +with default values to help in the configuration process. Explanations of respective settings are also available in +this example file. + +The configuration file tell the application runner (e.g. `Gunicorn`_, ``pserve`` or similar WSGI HTTP Server), how to +execute `Weaver` as well as all settings to provide in order to personalize the application. All settings specific to +`Weaver` employ the format ``weaver.``. + +Following is a partial list of most predominant settings. Note that all following settings should be applied under +section ``[app:main]`` of `weaver.ini.example`_ for the application to resolve them. + +- | ``weaver.configuration = ADES|EMS`` + | + | Tells the application in which mode to run. Enabling `ADES` for instance will disable some `EMS`-specific + | operations such as dispatching `Workflow`_ process steps to known remote `ADES` servers. + +- | ``weaver.url = `` + | + | Defines the full URL (including HTTP protocol/scheme, hostname and optionally additional path suffix) that will + | be used as base URL for all other URL settings of `Weaver`. + +.. note:: + + This is the URL that you want displayed in responses (e.g.: ``processDescriptionURL`` or job ``location``). + For the effective URL employed by the WSGI HTTP server, refer to ``[server:main]`` section of `weaver.ini.example`_. + +- | ``weaver.wps = true|false`` + | + | Enables the WPS-1/2 endpoint. + + .. warning:: + + At the moment, this setting must be ``true`` to allow job execution as the worker monitors this endpoint. + This could change with future developments (see issue `#21 `_). + +- | ``weaver.wps_path = `` + | ``weaver.wps_url = `` + | (default: *path* ``/ows/wps``) + | + | Defines the URL to employ as WPS-1/2 endpoint. + | + | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``. + | Setting ``weaver.wps_path`` is ignored if its URL equivalent is defined. + | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is + | not strictly enforced. + +- | ``weaver.wps_output_dir = `` + | (default: ``/tmp``) + | + | Location where WPS outputs (results from jobs) will be stored for stage-out. This directory should be mapped to + | `Weaver`'s WPS output URL to serve them externally as needed. + +- | ``weaver.wps_output_path = `` + | ``weaver.wps_output_url = `` + | (default: *path* ``/wpsoutputs``) + | + | Endpoint that will be employed as prefix to refer to WPS outputs (job results). + | + | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``. + | Setting ``weaver.wps_output_path`` is ignored if its URL equivalent is defined. + | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is + | not strictly enforced. + +- | ``weaver.wps_workdir = `` + | (default: uses automatically generated temporary directory if none specified) + | + | Prefix where process job worker should execute the process from. + +- | ``weaver.wps_restapi = true|false`` + | (default: ``true``) + | + | Enable the WPS-REST endpoint. + +.. note:: + + `Weaver` looses most, if not all, of its useful features without this, and there won't be much point in using + it without REST endpoint, but it should technically be possible to run it as WPS-1/2 only if desired. + +- | ``weaver.wps_restapi_path = `` + | ``weaver.wps_restapi_url = `` + | (default: *path* ``/``) + | + | Endpoint that will be employed as prefix to refer to WPS-REST requests + | (including but not limited to |ogc-proc-api|_ schemas). + | + | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``. + | Setting ``weaver.wps_restapi_path`` is ignored if its URL equivalent is defined. + | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is + | not strictly enforced. + +- | ``weaver.wps_metadata_[...]`` settings group + | + | Metadata fields that will be rendered by either or both the WPS-1/2 and WPS-REST endpoints (`GetCapabilities`_). + +- | ``weaver.wps_email_[...]`` settings group + | + | Defines configuration email notification functionality on job completion. + | + | Encryption settings as well as custom email templates are available. Email notifications are sent only on job + | completion if an email was provided in the `Execute`_ request body. + +.. seealso:: + - `Execute`_ request details. -.. todo:: complete docs +.. note:: + + Refer to `weaver.ini.example`_ for the extended list of applicable settings. + Some advanced configuration settings are also described in the below sections. Configuration of Data Sources @@ -59,13 +164,16 @@ To disable this feature and avoid any auto-deployment provided by this functiona Configuration of Request Options ======================================= -.. versionadded:: 1.8.0 - .. todo:: complete docs +``weaver.ssl_verify`` + + +.. versionadded:: 1.8.0 `request_options.yml.example`_ + Starting the Application ======================================= @@ -76,12 +184,3 @@ Starting the Application - need to start ``gunicorn/pserve`` (example `Dockerfile-manager`_) - need to start ``celery`` worker (example `Dockerfile-worker`_) - -.. _weaver.config: ../../../config -.. _weaver.ini.example: ../../../config/weaver.ini.example -.. _data_sources.json.example: ../../../config/data_sources.json.example -.. _wps_processes.yml.example: ../../../config/wps_processes.yml.example -.. _request_options.yml.example: ../../../config/request_options.yml.example -.. _Dockerfile-manager: ../../../docker/Dockerfile-manager -.. _Dockerfile-worker: ../../../docker/Dockerfile-worker - diff --git a/docs/source/processes.rst b/docs/source/processes.rst index 5793161ac..5ff93063e 100644 --- a/docs/source/processes.rst +++ b/docs/source/processes.rst @@ -244,6 +244,14 @@ Execution of a process (Execute, Job) .. todo:: + + +When a job is executed by specifying the ``notification_email`` field, the resulting process execution will send an +email to the specified address with successful or failure details. The format of the email is configurable from +`weaver.ini.example`_ file + +.. _exec-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes~1{process_id}~1jobs%2Fpost + .. _GetStatus: Monitoring of a process (GetStatus) diff --git a/docs/source/references.rst b/docs/source/references.rst index 9da3e2310..c4b42da88 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -24,3 +24,14 @@ .. _ogc-home: `ogc`_ .. |ogc-proc-api| replace:: OGC API - Processes .. _ogc-proc-api: https://github.com/opengeospatial/wps-rest-binding + +.. _Gunicorn: http://gunicorn.org/ +.. _MongoDB: https://www.mongodb.com/ + +.. _weaver.config: ../../../config +.. _weaver.ini.example: ../../../config/weaver.ini.example +.. _data_sources.json.example: ../../../config/data_sources.json.example +.. _wps_processes.yml.example: ../../../config/wps_processes.yml.example +.. _request_options.yml.example: ../../../config/request_options.yml.example +.. _Dockerfile-manager: ../../../docker/Dockerfile-manager +.. _Dockerfile-worker: ../../../docker/Dockerfile-worker diff --git a/docs/source/running.rst b/docs/source/running.rst index a78dabeda..50fbf3484 100644 --- a/docs/source/running.rst +++ b/docs/source/running.rst @@ -1,4 +1,5 @@ .. _running: +.. include:: references.rst **************** Running Weaver @@ -29,8 +30,6 @@ It will be available under the configured URL endpoint in ``weaver/config/weaver If everything was configured correctly, calling this URL (default: ``http://localhost:4001``) should provide a response containing a JSON body with basic information about Weaver. -.. _Gunicorn: http://gunicorn.org/ -.. _MongoDB: https://www.mongodb.com/ Using WPS Application =====================