wmo-im · tomkralidis · Sep 11, 2024 · Sep 5, 2024 · Sep 6, 2024 · Sep 6, 2024
diff --git a/.gitignore b/.gitignore
@@ -18,6 +18,7 @@ develop-eggs
 lib
 lib64
 __pycache__
+venv
 
 # Installer logs
 pip-log.txt

diff --git a/docs/README.md b/docs/README.md
@@ -6,7 +6,7 @@ format.  [Jupyter](https://jupyter.org) notebooks are also used for in-depth cod
 
 ## Setup
 To update the documentation, ensure that Sphinx, nbsphinx and Jupyter are installed on your system (hint:
-run `pip install -r requirements-dev.txt` to install the dependencies).  From here, `make html` will
+run `pip install -r requirements.txt` to install the dependencies).  From here, `./make html` will
 build the documentation, which you can serve using any standard web server.
 
 ## Jupyter

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/alert_preview.png b/docs/source/_static/cap/alert_preview.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/download_view_alert.png b/docs/source/_static/cap/download_view_alert.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/test.png b/docs/source/_static/cap/test.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -36,6 +36,7 @@ The user guide helps you setup your own wis2box instance.
    user/gts-headers-in-wis2
    user/public-services-setup
    user/downloading-data
+   user/cap-alerts
 
 Reference guide
 ===============

diff --git a/docs/source/user/cap-alerts.rst b/docs/source/user/cap-alerts.rst
@@ -0,0 +1,139 @@
+.. _cap-alerts:
+
+Publishing CAP Alerts to a wis2box
+==================================
+
+Overview
+--------
+The Common Alerting Protocol (CAP) is a simple but general format for exchanging all-hazard emergency alerts and public warnings over all kinds of networks, see the full specification `here <https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2.html>`_.
+
+This section provides guidance one 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.
+
+.. note::
+   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:
+
+1. *Dataset Creation:* Configure the dataset in the wis2box to store the CAP alerts.
+2. *MQTT Configuration:* 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`.
+
+.. note::
+   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: Select Template
+   :width: 400
+
+Enter the relevant missing information and create the dataset using your processes/wis2box token.
+
+.. image:: ../_static/cap/submit_dataset.png
+   :alt: Submit Dataset
+   :width: 800
+
+Now the dataset is created, note down the dataset ID, as it will be required in the next step.
+
+MQTT Configuration
+------------------
+Begin by logging in to the CAP Composer.
+
+.. note::
+   We will assume that you have the necessary admin rights to configure the CAP Composer. If you do not, please contact your CAP focal point.
+
+Navigate to 'CAP Alerts', then 'MQTT Brokers' in the left-hand menu.
+
+.. image:: ../_static/cap/mqtt_brokers_menu.png
+   :alt: MQTT Brokers Menu
+   :width: 300
+
+Click on the 'Add MQTT Broker' button in the top-right corner to add a new broker. You should see the following form:
+
+.. image:: ../_static/cap/broker_configuration.png
+   :alt: MQTT Broker Configuration
+   :width: 600
+
+Here, we should fill the following fields:
+
+- **Name**: A name for the broker.
+- **Host**: The ``WIS2BOX_BROKER_HOST`` environment variable from the wis2box configuration.
+- **Port**: The ``WIS2BOX_BROKER_PORT`` environment variable from the wis2box configuration.
+- **Username**: The ``WIS2BOX_BROKER_USERNAME`` environment variable from the wis2box configuration.
+- **Password**: The ``WIS2BOX_BROKER_PASSWORD`` environment variable from the wis2box configuration.
+- **WIS2 Node**: Confirmation that the MQTT broker is a WIS2 node (defaults to True).
+- **Dataset ID**: The dataset ID of the dataset created in the previous step.
+
+Once you have filled in the form, click the *Save* button to save the broker configuration.
+
+You will be redirected back to the 'MQTT Brokers' page, where you should see the newly added broker.
+
+.. image:: ../_static/cap/mqtt_broker_list.png
+   :alt: MQTT Broker List
+   :width: 600
+
+Publishing an Alert
+-------------------
+Let's begin by creating a CAP alert. This can be done by navigating to 'CAP Alerts', then 'Alerts' in the left-hand menu, and clicking the *Add Alert* button in the top-right corner.
+
+.. image:: ../_static/cap/alerts_menu.png
+   :alt: Alerts Menu
+   :width: 300
+
+.. note::
+   For more information on how to create a CAP alert, please see the `CAP Composer documentation on creating alerts <https://nmhs-cms.readthedocs.io/en/stable/_docs/Manage-CAP-Alerts.html#creating-a-cap-alert>`_.
+
+Once the alert is finished, if you are a CAP approver you should see a *Publish* button at the bottom:
+
+.. image:: ../_static/cap/publish_cap_alert.png
+   :alt: Publish Alert
+   :width: 300
+
+On clicking the *Publish* button, the alert XML file will automatically be created, signed, and published to your wis2box.
+
+.. note::
+   If you are a CAP composer, you will only be able to submit the alert for moderation. It is then the responsibility of the CAP approver to approve and publish the alert.
+
+You can view the status of the published alert in the 'CAP Alerts', then 'MQTT Broker Events' section of the CAP Composer.
+
+.. image:: ../_static/cap/mqtt_event_list.png
+   :alt: MQTT Event List
+   :width: 600
+
+Additional diagnostic information can be found by clicking the *Inspect* button.
+
+Verifying Receipt of a Published Alert and Viewing the Alert
+------------------------------------------------------------
+We can verify that the alert has been successfully published to the wis2box by monitoring the dataset in the wis2box-webapp.
+
+Navigate to the 'Monitoring' page in the wis2box-webapp, and select the dataset that you created in the previous steps.
+
+.. note::
+   If you do not see the dataset, ensure that the datetime range selected includes the time of the alert publication.
+
+.. image:: ../_static/cap/monitoring_dashboard.png
+   :alt: Monitoring Dashboard
+   :width: 800
+
+Provided the publication was successful, you will see a bar in the 'Notifications' section. If you scroll down to the 'Published Data' section, the signed and verified CAP alert should appear in the table to download and view.
+
+.. image:: ../_static/cap/download_view_alert.png
+   :alt: Published Data
+   :width: 800
+
+On clicking the *View Alert* button, you should see a visualization of the CAP alert you created earlier.
+
+.. image:: ../_static/cap/alert_preview.png
+   :alt: View Alert
+   :width: 800
+
+Congratulations! You have successfully published a CAP alert to a wis2box using the CAP Composer.
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 @@
 
 .. 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 @@
 
    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 @@
    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,7 +162,8 @@
    cat wis2box.env | grep WIS2BOX_WEBAPP
 
 
+.. _adding-datasets:
 Adding datasets
 ---------------
 
 In order to publish data using the wis2box you need to create a dataset with discovery metadata and data mappings plugins. The metadata provides the data description needed for users to discover your data when searching the WIS2 Global Discovery Catalogue.
@@ -190,8 +191,8 @@
    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.