diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..fb5c9ad --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,13 @@ +.. _api: + +API +=== + +Overview +-------- + +Discovery +--------- + +Validation +----------- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 85d5f1f..88cdd93 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -3,9 +3,12 @@ Configuration ============= +Main configuration environment variables +---------------------------------------- + ``wis2-gdc`` configuration is driven by the following environment variables, which are managed in ``wis2-gdc.env``: -.. csv-table:: Environment variables +.. csv-table:: Main environment variables :widths: 30 30 30 :header: Name,Description,Default @@ -24,6 +27,39 @@ Configuration ``WIS2_GDC_REJECT_ON_FAILING_ETS``,whether the GDC should stop ingest based on on failing record,``true`` ``WIS2_GDC_RUN_KPI``,whether the GDC should run KPI as part of ingest,``false`` +API configuration environment variables +--------------------------------------- + +If you wish to update the API configuration, you can set the below values accordingly (to override the pygeoapi defaults): + +.. csv-table:: pygeoapi configuration environment variables + :widths: 30 30 + :header: Name,Description + + ``WIS2_GDC_METADATA_IDENTIFICATION_TITLE``,API title + ``WIS2_GDC_METADATA_IDENTIFICATION_DESCRIPTION``,API description + ``WIS2_GDC_METADATA_IDENTIFICATION_KEYWORDS``,API keywords + ``WIS2_GDC_METADATA_IDENTIFICATION_TERMS_OF_SERVICE``,API terms of service + ``WIS2_GDC_METADATA_IDENTIFICATION_URL``,URL related to API + ``WIS2_GDC_METADATA_LICENSE_NAME``,API license name + ``WIS2_GDC_METADATA_LICENSE_URL``,API license URL + ``WIS2_GDC_METADATA_PROVIDER_NAME``,API provider name + ``WIS2_GDC_METADATA_PROVIDER_URL``,API provider URL + ``WIS2_GDC_METADATA_CONTACT_NAME``,API contact name + ``WIS2_GDC_METADATA_CONTACT_POSITION``,API contact position + ``WIS2_GDC_METADATA_CONTACT_ADDRESS``,API contact address + ``WIS2_GDC_METADATA_CONTACT_CITY``,API contact city + ``WIS2_GDC_METADATA_CONTACT_STATEORPROVINCE``,API contact state or province + ``WIS2_GDC_METADATA_CONTACT_POSTALCODE``,API contact postal code + ``WIS2_GDC_METADATA_CONTACT_COUNTRY``,API contact country + ``WIS2_GDC_METADATA_CONTACT_PHONE``,API contact phone number (in format ``+xx-xxx-xxx-xxxx``) + ``WIS2_GDC_METADATA_CONTACT_FAX``,API contact fax number (in format ``+xx-xxx-xxx-xxxx``) + ``WIS2_GDC_METADATA_CONTACT_EMAIL``,API contact email + ``WIS2_GDC_METADATA_CONTACT_URL``,API contact URL + ``WIS2_GDC_METADATA_CONTACT_HOURS``,API contact hours of service + ``WIS2_GDC_METADATA_CONTACT_INSTRUCTIONS``,API contact instructions + ``WIS2_GDC_METADATA_CONTACT_ROLE``,API contact role + Global Broker environment variables ----------------------------------- @@ -55,12 +91,12 @@ A default installation with minimal configuration changes per below satisfies mo The ``wis2-gdc`` Docker Compose file also contains additional environment variables (see ``docker-compose.yml`` to adjust accordingly). In most cases, these values do not need adjustment. -Application specific configuration ----------------------------------- +Application specific configurations +----------------------------------- -Application specific configurations can be found in the following files: +Application specific configurations can be found in the following files (for direct editing if needed): -.. csv-table:: Applicaiton specific configuration files +.. csv-table:: Application specific configuration files :widths: 30 30 :header: Filepath,Description diff --git a/docs/source/index.rst b/docs/source/index.rst index 60f01bf..5149fad 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,10 +26,7 @@ reference documentation on all aspects of the project. configuration administration running - openapi - transactions - admin-api - security + api contributing support license diff --git a/docs/source/running.rst b/docs/source/running.rst new file mode 100644 index 0000000..af2a02f --- /dev/null +++ b/docs/source/running.rst @@ -0,0 +1,52 @@ +.. _running: + +Running +======= + +As defined by the WIS2 Technical Regulations, wis2-gdc is an event driven service which listens to WIS2 Global Broker services in ordder to manage discovery metadata publication. + +Interactive discovery metadata workflows +---------------------------------------- + +To register metadata manually, login to the ``wis2-gdc-management`` container and run the following commands: + +.. code-block:: + + # loading metadata manually (single file) + wis2-gdc register /path/to/wcmp2-file.json + + # loading metadata manually (directory of .json files) + wis2-gdc register /path/to/dir/of/wcmp2-files + + # loading metadata manually (from URL) + wis2-gdc register https://example.org/wcmp2-file.json + + # deleting metadata by identifier + wis2-gdc unregister "urn:wmo:md:ca-eccc-msc:id123" + + # load all WCMP2 metadata from known wis2box deployments (https://demo.wis2box.wis.wmo.int) + wis2-gdc sync wis2box + + # create a metadata archive zipfile + wis2-gdc archive foo.zip + +Services +-------- + +The following publically facing services are running when wis2-gdc is started: + +- API (port 80) +- Broker (port 1883) + +TLS/SSL +------- + +To enable SSL, it is advised to setup SSL on a proxy server and "proxy pass" to wis2-gdc services accordingly. + +Below are examples of adding HTTP and MQTT proxies to Nginx: + +TODO: add nginx snippets + +.. note:: + + It is strongly recommended to run services using TLS/SSL to offer HTTPS and MQTTS diff --git a/docs/source/support.rst b/docs/source/support.rst new file mode 100644 index 0000000..409a795 --- /dev/null +++ b/docs/source/support.rst @@ -0,0 +1,9 @@ +.. _support: + +Support +======= + +Community +--------- + +Please see the wis2-gdc `issue tracker `_ page to ask questions, open issues, getting support, and how to get involved.