Maaike updates (#467)

* ubuntu 20.04

* wis2box-api health check

* additional documentation updates

* Update getting-started.rst

* Update setup.rst

---------

Co-authored-by: Tom Kralidis <tomkralidis@gmail.com>

Author: maaikelimper

docker-compose.yml

@@ -43,6 +43,10 @@ services:
         condition: service_healthy
     volumes:
       - api-config:/data/wis2box/config/pygeoapi/:rw
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost/oapi/admin/resources"]
+      interval: 5s
+      retries: 100
 
   minio:
     container_name: wis2box-minio
@@ -90,7 +94,7 @@ services:
     #     soft: -1
     #     hard: -1
     healthcheck:
-      test: ["CMD", "curl", "http://localhost:9200"]
+      test: ["CMD", "curl", "-f", "http://localhost:9200"]
       interval: 5s
       retries: 100
 
@@ -124,7 +128,7 @@ services:
       mosquitto:
         condition: service_started
       wis2box-api:
-        condition: service_started
+        condition: service_healthy
     command: ["wis2box", "pubsub" , "subscribe", "--broker", "http://wis2box-minio:9000", "--topic", "wis2box-storage/#"]
 
   wis2box-auth:

docs/source/user/getting-started.rst

@@ -4,8 +4,7 @@ Getting started
 ===============
 
 wis2box can be run on any Linux instance (bare metal or cloud hosted VM) with Python, Docker and Docker Compose installed. 
-
-The recommended OS is Ubuntu 22.04 LTS.
+The recommended OS is Ubuntu 20.04 LTS.
 
 .. note::
 
@@ -40,6 +39,20 @@ wis2box requires the following prior to installation:
    Docker Engine, 20.10.14 or higher
    Docker Compose, 1.29.2
 
+The following commands be used to setup the required software on Ubuntu 20.04 LTS:
+
+.. code-block:: bash
+    
+    sudo mkdir -m 0755 -p /etc/apt/keyrings
+    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg
+    sudo chmod a+r /etc/apt/keyrings/docker.gpg
+    sudo echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+    sudo apt-get -y update
+    sudo apt-get install -y docker-ce unzip python3-pip
+    sudo pip3 install pip --upgrade
+    sudo pip3 install pyopenssl --upgrade
+    sudo pip3 install docker-compose==1.29.2 requests==2.26.0 urllib3==1.26.0
+
 The following commands can be used to inspect the available versions of Python, Docker and Docker Compose on your system:
 
 .. code-block:: bash

docs/source/user/setup.rst

@@ -31,23 +31,29 @@ Copy this file to your working directory, and update it to suit your needs.
 
    cp examples/config/wis2box.env dev.env
 
-.. note::
-
-   You must map ``WIS2BOX_HOST_DATADIR`` to the absolute path of a directory on your host machine. This path will be mapped to ``/data/wis2box`` inside the wis2box-management container
-   To enable external data sharing you must set ``WIS2BOX_URL`` to the URL pointing to where your host is exposed on the public network.
-
 .. note::
    Please ensure you set ``WIS2BOX_BROKER_PASSWORD`` and ``WIS2BOX_STORAGE_PASSWORD`` to your own unique values.
 
    You will use these passwords to connect to your broker and MinIO storage to help you debug your wis2box services.
 
    Do not share these passwords with external parties.
 
-The next sections assume you use an environment variable for ``WIS2BOX_HOST_DATADIR`` that is set to same value used in ``dev.env``:
+.. note::
+
+   You must map ``WIS2BOX_HOST_DATADIR`` to the absolute path of a directory on your host machine. This path will be mapped to ``/data/wis2box`` inside the **wis2box-management** container.
+   To enable external data sharing you must set ``WIS2BOX_URL`` to the URL pointing to where your host is exposed on the public network.
+
+For example you can create a ``wis2box-data`` directory in your home directory as follows:
+
+.. code-block:: bash
+
+   mkdir /home/<your-username>/wis2box-data
+
+And you can edit ``dev.env`` to match the location
 
 .. code-block:: bash
 
-   export WIS2BOX_HOST_DATADIR=/home/example/wis2box-data
+   WIS2BOX_HOST_DATADIR=/home/<your-username>/wis2box-data
 
 Data mappings
 -------------
@@ -63,13 +69,13 @@ For example, if your incoming data contains ``.bufr4`` files containing synoptic
 
 .. code-block:: bash
 
-   cp synop-bufr-mappings.yml ${WIS2BOX_HOST_DATADIR}/data-mappings.yml
+   cp synop-bufr-mappings.yml ~/wis2box-data/data-mappings.yml
 
 .. note::
 
    The file should be called ``data-mappings.yml`` and should be placed in the directory you defined as ``WIS2BOX_HOST_DATADIR``.
 
-Edit ``${WIS2BOX_HOST_DATADIR}/data-mappings.yml``:
+Edit ``~/wis2box-data/data-mappings.yml``:
 
  * Replace ``country`` with your corresponding ISO 3166 alpha-3 country code in lowercase
  * Replace ``centre_id`` with the string identifying the centre running your wis2node in lowercase, alphanumeric characters
@@ -160,10 +166,10 @@ You can copy this file to ``metadata/station/station_list.csv`` in your $WIS2BOX
 
 .. code-block:: bash
 
-   mkdir -p ${WIS2BOX_HOST_DATADIR}/metadata/station
-   cp station_list.csv ${WIS2BOX_HOST_DATADIR}/metadata/station
+   mkdir -p ~/wis2box-data/metadata/station
+   cp station_list.csv ~/wis2box-data/metadata/station
 
-And edit ``${WIS2BOX_HOST_DATADIR}/metadata/station/station_list.csv`` to include the data for your stations.
+And edit ``~/wis2box-data/metadata/station/station_list.csv`` to include the data for your stations.
 
 .. note::
 
@@ -181,7 +187,13 @@ Discovery metadata records can be defined using the YAML syntax shared via ``WIS
 
 An example is provided in ``surface-weather-observations.yml``. Each dataset requires its own discovery metadata configuration file.
 
-You can copy the file ``surface-weather-observations.yml`` to the directory you defined for ``WIS2BOX_HOST_DATADIR`` and update it to provide the correct discovery metadata for your dataset:
+You can copy the file ``surface-weather-observations.yml`` to the directory defined for ``WIS2BOX_HOST_DATADIR``:
+
+.. code-block:: bash
+
+   cp examples/config/surface-weather-observations.yml ~/wis2box-data/metadata/station
+
+And update it to provide the correct discovery metadata for your dataset:
 
 * replace ``[country].[centre_id].data.core.weather.surface-based-observations.synop`` with the topic as previously used in ``$WIS2BOX_HOST_DATADIR/data-mappings.yml``
 * text provided in ``identification.title`` and ``identification.abstract`` will be displayed in the wis2box user interface
@@ -205,6 +217,16 @@ 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::
+
+   If you get the error:
+
+   ``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 ``sudo usermod -aG docker <your-username>``.
+   Logout and log back in so that your group membership is re-evaluated.
+
+
 Once the command above is completed, check that all services are running (and healthy).
 
 .. code-block:: bash