Public services setup¶
To share your data with the WIS2 network, you need to expose some of your wis2box services to the Global Services:
The Global Cache needs to be able to access to your HTTP endpoint to download data published by your wis2box instance
The Global Broker needs to be able to subscribe to your MQTT endpoint to receive WIS2 notifications published by your wis2box instance
SSL¶
To enable HTTPS and MQTTS on your wis2box you can run wis2box with the option –ssl:
python3 wis2box-ctl.py --ssl start
When running wis2box with SSL, you have to set additional environment variables in your dev.env defining the location of your SSL certificate and private key:
WIS2BOX_SSL_CERT=/etc/letsencrypt/live/example.wis2box.io/fullchain.pem
WIS2BOX_SSL_KEY=/etc/letsencrypt/live/example.wis2box.io/privkey.pem
Please remember to update the WIS2BOX_URL environment variable after enabling SSL, ensuring your URL starts with https://.
Nginx (HTTP)¶
wis2box runs a local nginx container allowing access to the following HTTP based services on port 80:
Function |
URL |
|---|---|
API (wis2box-api) |
WIS2BOX_URL/oapi |
UI (wis2box-ui) |
WIS2BOX_URL/ |
Storage (incoming data) (minio:wis2box-incoming) |
WIS2BOX_URL/wis2box-incoming |
Storage (public data) (minio:wis2box-public) |
WIS2BOX_URL/data |
You can edit nginx/nginx.conf to control which services are exposed through the nginx-container include in your stack.
You can edit docker-compose.override.yml to change the port on which the web-proxy service exposes HTTP on the localhost.
Note
The WIS2 notifications published by the wis2box includes the path <wis2box-url>/data/.
This path has to be publicly accessible by the client receiving the WIS2 notification over MQTT, or the data referenced cannot be downloaded
To share your data with the WIS2 network, ensure that WIS2BOX_URL as defined in dev.env points to the externally accessible URL for your HTTP services.
After updating WIS2BOX_URL, please stop and start your wis2box using wis2box-ctl.py and republish your data using the command wis2box metadata discovery publish.
Note
By default the environment variable WIS2BOX_URL resolves to http://localhost.
This URL will define the /data URL used in the canonical link as part of your data in MQTT, as well as the dataset location in your discovery metadata.
wis2box API¶
The wis2box API uses pygeoapi, which implements the OGC API suite of standards, to provide programmatic access to the data collections hosted in your wis2box.
Note
Currently, the default API backend in the wis2box stack uses Elasticsearch.
A dedicated Docker-volume es-data is created on your host when you start your wis2box.
As long as this volume is not deleted you can remove/update the containers in the wis2box stack without losing data.
wis2box user interface¶
The wis2box user interface uses the wis2box API to visualize the data configured and shared through your wis2box.
The ‘map’ or ‘explore’ option of each dataset allows you to visualize Weather Observations per station.
Mosquitto (MQTT)¶
By default, wis2box uses its own internal Mosquitto container to publish WIS2 notifications.
To allow the WIS2 Global Broker to subscribe to WIS2 notifications from your wis2box you have 2 options:
enable access to internal broker running in the MQTT container on your wis2box host
configure your wis2box to use an external broker
Internal broker¶
The internal MQTT broker uses the default username/password of wis2box/wis2box. Before opening the MQTT port for external access, it is recommended to set a unique password as follows:
WIS2BOX_BROKER_USERNAME=wis2box-utopia
WIS2BOX_BROKER_PASSWORD=myuniquepassword
WIS2BOX_BROKER_PUBLIC=mqtt://${WIS2BOX_BROKER_USERNAME}:${WIS2BOX_BROKER_PASSWORD}@mosquitto:1883
# update minio settings after updating broker defaults
MINIO_NOTIFY_MQTT_USERNAME_WIS2BOX=${WIS2BOX_BROKER_USERNAME}
MINIO_NOTIFY_MQTT_PASSWORD_WIS2BOX=${WIS2BOX_BROKER_PASSWORD}
MINIO_NOTIFY_MQTT_BROKER_WIS2BOX=tcp://${WIS2BOX_BROKER_HOST}:${WIS2BOX_BROKER_PORT}
The internal MQTT broker is accessible on the host mosquitto within the Docker network used by wis2box.
By default port 1883 of the mosquitto container is mapped to port 1883 of the host running wis2box.
By exposing port 1883 on your host, the Global Broker will be able to subscribe directly to the internal MQTT broker on the wis2box.
Note
The everyone user is defined by default for public readonly access (origin/#) as per WIS2 Node requirements.
External broker¶
If you do not wish to expose the internal MQTT broker on your wis2box, you can configure your wis2box to publish WIS2 notifications to an external broker by setting the environment variable WIS2BOX_BROKER_PUBLIC.
# For example to use an external broker at host=example.org
WIS2BOX_BROKER_PUBLIC=mqtts://username:password@example.org:8883
Note
The everyone user is defined by default for public readonly access (origin/#) as per WIS2 Node requirements.