update docs

wmo-im · Dec 1, 2024 · b9dea3f · b9dea3f
1 parent e1085ef
commit b9dea3f
Show file tree

Hide file tree

Showing 5 changed files with 116 additions and 9 deletions.
diff --git a/docs/source/api.rst 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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,9 @@
+.. _support:
+
+Support
+=======
+
+Community
+---------
+
+Please see the wis2-gdc `issue tracker <https://github.com/wmo-im/wis2-gdc>`_ page to ask questions, open issues, getting support, and how to get involved.