docs: add CAP Composer integration guide 1

wmo-im · Sep 5, 2024 · d1cbd59 · d1cbd59
1 parent 9827ce7
commit d1cbd59
Show file tree

Hide file tree

Showing 16 changed files with 50 additions and 9 deletions.
diff --git a/docs/source/_static/cap/add_cap_alert.png b/docs/source/_static/cap/add_cap_alert.png
diff --git a/docs/source/_static/cap/add_mqtt_broker.png b/docs/source/_static/cap/add_mqtt_broker.png
diff --git a/docs/source/_static/cap/alerts_menu.png b/docs/source/_static/cap/alerts_menu.png
diff --git a/docs/source/_static/cap/broker_configuration.png b/docs/source/_static/cap/broker_configuration.png
diff --git a/docs/source/_static/cap/dataset_confirmation.png b/docs/source/_static/cap/dataset_confirmation.png
diff --git a/docs/source/_static/cap/monitoring_dashboard.png b/docs/source/_static/cap/monitoring_dashboard.png
diff --git a/docs/source/_static/cap/mqtt_broker_list.png b/docs/source/_static/cap/mqtt_broker_list.png
diff --git a/docs/source/_static/cap/mqtt_brokers_menu.png b/docs/source/_static/cap/mqtt_brokers_menu.png
diff --git a/docs/source/_static/cap/mqtt_event_list.png b/docs/source/_static/cap/mqtt_event_list.png
diff --git a/docs/source/_static/cap/notification_bar.png b/docs/source/_static/cap/notification_bar.png
diff --git a/docs/source/_static/cap/publish_cap_alert.png b/docs/source/_static/cap/publish_cap_alert.png
diff --git a/docs/source/_static/cap/submit_dataset.png b/docs/source/_static/cap/submit_dataset.png
diff --git a/docs/source/_static/cap/template_selection.png b/docs/source/_static/cap/template_selection.png
diff --git a/docs/source/_static/cap/wis2_node_checkbox.png b/docs/source/_static/cap/wis2_node_checkbox.png
diff --git a/docs/source/user/cap-alerts.rst b/docs/source/user/cap-alerts.rst
@@ -0,0 +1,40 @@
+.. _cap-alerts:
+
+Publishing CAP Alerts to a wis2box
+=================
+
+Here we explain how one can use the `CAP Composer <https://github.com/wmo-raf/cap-composer>`_ to automate the publishing of CAP alerts to a wis2box.
+
+Requirements
+------------
+In addition to a running wis2box, you will need to install, configure, and run the CAP Composer. For information on how to do this, please consult the `CAP Composer documentation <https://nmhs-cms.readthedocs.io/en/stable/_docs/Manage-CAP-Alerts.html>`_.
+
+Process Outline
+---------------
+For automated publishing of CAP alerts to a wis2box, we will need to perform the following steps:
+* Create a dataset in the wis2box to store the CAP alerts.
+* Configure your wis2box broker details in the CAP Composer.
+
+Dataset Creation
+----------------
+Firstly, there must be a dataset in the wis2box for the CAP alerts to be stored. To create a dataset, simply navigate to the 'Dataset Editor' page in the wis2box-webapp, available on your host at `http://<your-public-ip>/wis2box-webapp`. For more information on how to create a dataset, please see the :ref:`adding-datasets` section of the wis2box setup guide.
+
+When creating a new dataset for CAP alerts, ensure that the 'weather/advisories-warnings' template is selected:
+
+.. image:: ../_static/cap/template_selection.png
+   :alt: CAP Dataset
+   :align: center
+
+To finish.
+
+MQTT configuration
+------------------
+To finish.
+
+Publishing an Alert
+-------------------
+To finish.
+
+Verifying Receipt of a Published Alert
+--------------------------------------
+To finish.
diff --git a/docs/source/user/setup.rst b/docs/source/user/setup.rst
@@ -3,7 +3,7 @@
 Installation and configuration
 ==============================
 
-This section summarizes the steps required to install a wis2box instance and setup your own datasets using initial configuration files 
+This section summarizes the steps required to install a wis2box instance and setup your own datasets using initial configuration files
 provided by using the ``wis2box-create-config.py`` script.
 
 Ensure you have Docker, Docker Compose and Python installed on your host, as detailed in :ref:`getting-started`.
@@ -32,11 +32,11 @@ Run the following command to create the initial configuration files for your wis
 
 .. note::
 
-    The ``wis2box-create-config.py`` script will ask for a directory to store the configuration files. 
+    The ``wis2box-create-config.py`` script will ask for a directory to store the configuration files.
     Please provide the **absolute** path to the directory where you want to store the configuration files, for example ``/home/wis2box-user/wis2box-data``.
     This directory will be mapped to ``/data/wis2box`` **inside** the wis2box-management container.
 
-   The script will also ask for the URL of your wis2box. Please provide the public URL of your wis2box, for example ``http://mywis2box.example.com``. 
+   The script will also ask for the URL of your wis2box. Please provide the public URL of your wis2box, for example ``http://mywis2box.example.com``.
    For testing purpose you can also provide the internal IP address you use to access the host, for example ``http://192.168.0.3`` and you change the URL in configuration files at a later point in time.
 
    The script will propose to automatically create a password for ``WIS2BOX_WEBAPP_PASSWORD``. This password is used to access the wis2box-webapp interface.
@@ -68,17 +68,17 @@ This might take a while the first time, as Docker images will be downloaded.
 
    The ``wis2box-ctl.py`` program is used as a convenience utility around a set of Docker Compose commands.
    You can customize the ports exposed on your host by editing ``docker-compose.override.yml``.
-   
+
 .. note::
 
    In case you get errors from the Docker daemon stating 'Permission denied', such as:
 
    ``docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', PermissionError(13, 'Permission denied'))``
 
    Please ensure your username is added to the Docker group using the command:
-   
+
    ``sudo usermod -aG docker <your-username>``.
-   
+
    Logout and log back in so that your group membership is re-evaluated.
 
 
@@ -109,7 +109,7 @@ Check that all services are Up and not unhealthy:
    wis2box-webapp           sh /wis2box-webapp/ ...          Up (healthy)   4173/tcp
 
 
-Refer to the :ref:`troubleshooting` section if this is not the case. 
+Refer to the :ref:`troubleshooting` section if this is not the case.
 
 
 Runtime configuration
@@ -162,6 +162,7 @@ The values of ``WIS2BOX_WEBAPP_USERNAME`` and ``WIS2BOX_WEBAPP_PASSWORD`` can be
    cat wis2box.env | grep WIS2BOX_WEBAPP
 
 
+.. _adding-datasets:
 Adding datasets
 ---------------
 
@@ -190,8 +191,8 @@ A popup will appear where you can define your "centre-id" and the type of datase
    The centre-id has to be lowercase and use alphanumeric characters only.
    The dropdown list shows all currently registered centre-ids on WIS2 as well as any centre-id you have already created in wis2box.
 
-There are 2 pre-defined dataset types for "weather/surface-based-observations/synop" and "weather/surface-based-observations/temp". 
-We recommend using these pre-defined dataset types to publish your "synop" and "temp" data, respectively. 
+There are 2 pre-defined dataset types for "weather/surface-based-observations/synop" and "weather/surface-based-observations/temp".
+We recommend using these pre-defined dataset types to publish your "synop" and "temp" data, respectively.
 The predefined dataset will predefine the topic and data mappings for you.
 If you want to create a dataset for a different topic, you can select "other" and define the topic and data mappings yourself.