Initialisation de wis2box
Objectifs d'apprentissage
À la fin de cette session pratique, vous serez capable de :
- exécuter le script
wis2box-create-config.py
pour créer la configuration initiale - démarrer wis2box et vérifier l'état de ses composants
- consulter le contenu de wis2box-api
- accéder à wis2box-webapp
- se connecter au wis2box-broker local à l'aide de MQTT Explorer
Note
Les supports de formation actuels sont basés sur wis2box-release 1.1.0.
Consultez accessing-your-student-vm pour des instructions sur le téléchargement et l'installation de la pile logicielle wis2box si vous suivez cette formation en dehors d'une session de formation locale.
Préparation
Connectez-vous à votre VM désignée avec votre nom d'utilisateur et votre mot de passe, et assurez-vous d'être dans le répertoire wis2box
:
cd ~/wis2box
Création de la configuration initiale
La configuration initiale de wis2box nécessite :
- un fichier d'environnement
wis2box.env
contenant les paramètres de configuration - un répertoire sur la machine hôte à partager entre la machine hôte et les conteneurs wis2box, défini par la variable d'environnement
WIS2BOX_HOST_DATADIR
Le script wis2box-create-config.py
peut être utilisé pour créer la configuration initiale de votre wis2box.
Il vous posera une série de questions pour vous aider à configurer votre environnement.
Vous pourrez examiner et mettre à jour les fichiers de configuration une fois le script terminé.
Exécutez le script comme suit :
python3 wis2box-create-config.py
Répertoire wis2box-host-data
Le script vous demandera de saisir le répertoire à utiliser pour la variable d'environnement WIS2BOX_HOST_DATADIR
.
Notez que vous devez définir le chemin complet vers ce répertoire.
Par exemple, si votre nom d'utilisateur est username
, le chemin complet vers le répertoire est /home/username/wis2box-data
:
username@student-vm-username:~/wis2box$ python3 wis2box-create-config.py
Please enter the directory to be used for WIS2BOX_HOST_DATADIR:
/home/username/wis2box-data
The directory to be used for WIS2BOX_HOST_DATADIR will be set to:
/home/username/wis2box-data
Is this correct? (y/n/exit)
y
The directory /home/username/wis2box-data has been created.
URL de wis2box
Ensuite, il vous sera demandé de saisir l'URL de votre wis2box. Cette URL sera utilisée pour accéder à l'application web, à l'API et à l'interface utilisateur de wis2box.
Veuillez utiliser http://<your-hostname-or-ip>
comme URL.
Please enter the URL of the wis2box:
For local testing the URL is http://localhost
To enable remote access, the URL should point to the public IP address or domain name of the server hosting the wis2box.
http://username.wis2.training
The URL of the wis2box will be set to:
http://username.wis2.training
Is this correct? (y/n/exit)
Mots de passe WEBAPP, STORAGE et BROKER
Vous pouvez utiliser l'option de génération aléatoire de mots de passe lorsque vous y êtes invité pour WIS2BOX_WEBAPP_PASSWORD
, WIS2BOX_STORAGE_PASSWORD
, WIS2BOX_BROKER_PASSWORD
, ou définir vos propres mots de passe.
Ne vous inquiétez pas de mémoriser ces mots de passe, ils seront stockés dans le fichier wis2box.env
dans votre répertoire wis2box.
Vérification de wis2box.env
Une fois le script terminé, vérifiez le contenu du fichier wis2box.env
dans votre répertoire actuel :
cat ~/wis2box/wis2box.env
Ou consultez le contenu du fichier via WinSCP.
Question
Quelle est la valeur de WISBOX_BASEMAP_URL dans le fichier wis2box.env ?
Cliquez pour révéler la réponse
La valeur par défaut pour WIS2BOX_BASEMAP_URL est https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
.
Cette URL fait référence au serveur de tuiles OpenStreetMap. Si vous souhaitez utiliser un autre fournisseur de cartes, vous pouvez modifier cette URL pour pointer vers un autre serveur de tuiles.
Question
Quelle est la valeur de la variable d'environnement WIS2BOX_STORAGE_DATA_RETENTION_DAYS dans le fichier wis2box.env ?
Cliquez pour révéler la réponse
La valeur par défaut pour WIS2BOX_STORAGE_DATA_RETENTION_DAYS est de 30 jours. Vous pouvez modifier cette valeur pour un autre nombre de jours si vous le souhaitez.
Le conteneur wis2box-management exécute un cronjob quotidien pour supprimer les données plus anciennes que le nombre de jours défini par WIS2BOX_STORAGE_DATA_RETENTION_DAYS du bucket wis2box-public
et du backend API :
0 0 * * * su wis2box -c "wis2box data clean --days=$WIS2BOX_STORAGE_DATA_RETENTION_DAYS"
Note
Le fichier wis2box.env
contient des variables d'environnement définissant la configuration de votre wis2box. Pour plus d'informations, consultez la documentation wis2box.
N'éditez pas le fichier wis2box.env
à moins d'être sûr des modifications que vous effectuez. Des modifications incorrectes peuvent entraîner un dysfonctionnement de votre wis2box.
Ne partagez pas le contenu de votre fichier wis2box.env
avec qui que ce soit, car il contient des informations sensibles telles que des mots de passe.
Démarrer wis2box
Assurez-vous d'être dans le répertoire contenant les fichiers de définition de la pile logicielle wis2box :
cd ~/wis2box
Démarrez wis2box avec la commande suivante :
python3 wis2box-ctl.py start
Lors de la première exécution de cette commande, vous verrez la sortie suivante :
No docker-compose.images-*.yml files found, creating one
Current version=Undefined, latest version=1.1.0
Would you like to update ? (y/n/exit)
Sélectionnez y
et le script créera le fichier docker-compose.images-1.1.0.yml
, téléchargera les images Docker nécessaires et démarrera les services.
Le téléchargement des images peut prendre du temps en fonction de la vitesse de votre connexion Internet. Cette étape n'est requise que lors du premier démarrage de wis2box.
Vérifiez l'état avec la commande suivante :
python3 wis2box-ctl.py status
Répétez cette commande jusqu'à ce que tous les services soient opérationnels.
wis2box et Docker
wis2box fonctionne comme un ensemble de conteneurs Docker gérés par docker-compose.
Les services sont définis dans les différents fichiers docker-compose*.yml
qui se trouvent dans le répertoire ~/wis2box/
.
Le script Python wis2box-ctl.py
est utilisé pour exécuter les commandes Docker Compose sous-jacentes qui contrôlent les services wis2box.
Vous n'avez pas besoin de connaître les détails des conteneurs Docker pour exécuter la pile logicielle wis2box, mais vous pouvez consulter les fichiers docker-compose*.yml
pour voir comment les services sont définis. Si vous souhaitez en savoir plus sur Docker, vous pouvez consulter la documentation Docker.
Pour vous connecter au conteneur wis2box-management, utilisez la commande suivante :
python3 wis2box-ctl.py login
Notez qu'après vous être connecté, votre invite changera, indiquant que vous êtes maintenant dans le conteneur wis2box-management :
root@025381da3c40:/home/wis2box#
Dans le conteneur wis2box-management, vous pouvez exécuter diverses commandes pour gérer votre wis2box, telles que :
wis2box auth add-token --path processes/wis2box
: pour créer un jeton d'autorisation pour l'endpoint processes/wis2boxwis2box data clean --days=<number-of-days>
: pour nettoyer les données plus anciennes qu'un certain nombre de jours dans le bucket wis2box-public
Pour quitter le conteneur et revenir à votre machine hôte, utilisez la commande suivante :
exit
Exécutez la commande suivante pour voir les conteneurs Docker en cours d'exécution sur votre machine hôte :
docker ps --format "table {{.Names}} \t{{.Status}} \t{{.Image}}"
Vous devriez voir les conteneurs suivants en cours d'exécution :
NAMES STATUS IMAGE
nginx Up About a minute nginx:alpine
wis2box-auth Up About a minute ghcr.io/world-meteorological-organization/wis2box-auth:1.1.0
mqtt_metrics_collector Up About a minute ghcr.io/world-meteorological-organization/wis2box-mqtt-metrics-collector:1.1.0
wis2box-ui Up 3 minutes ghcr.io/world-meteorological-organization/wis2box-ui:1.1.0
wis2box-management Up About a minute ghcr.io/world-meteorological-organization/wis2box-management:1.1.1
wis2box-minio Up 4 minutes (healthy) minio/minio:RELEASE.2024-08-03T04-33-23Z-cpuv1
wis2box-api Up 3 minutes (healthy) ghcr.io/world-meteorological-organization/wis2box-api:1.1.0
wis2box-webapp Up 4 minutes (healthy) ghcr.io/world-meteorological-organization/wis2box-webapp:1.1.0
elasticsearch Up 4 minutes (healthy) docker.elastic.co/elasticsearch/elasticsearch:8.6.2
mosquitto Up 4 minutes ghcr.io/world-meteorological-organization/wis2box-broker:1.1.0
grafana Up 4 minutes grafana/grafana-oss:9.0.3
elasticsearch-exporter Up 4 minutes quay.io/prometheuscommunity/elasticsearch-exporter:latest
wis2downloader Up 4 minutes (healthy) ghcr.io/wmo-im/wis2downloader:v0.3.2
prometheus Up 4 minutes prom/prometheus:v2.37.0
loki Up 4 minutes grafana/loki:2.4.1
Ces conteneurs font partie de la pile logicielle wis2box et fournissent les différents services nécessaires pour exécuter le wis2box.
Exécutez la commande suivante pour voir les volumes Docker en cours d'exécution sur votre machine hôte :
docker volume ls
Vous devriez voir les volumes suivants :
- wis2box_project_auth-data
- wis2box_project_es-data
- wis2box_project_htpasswd
- wis2box_project_minio-data
- wis2box_project_prometheus-data
- wis2box_project_loki-data
- wis2box_project_mosquitto-config
Ainsi que certains volumes anonymes utilisés par les différents conteneurs.
Les volumes commençant par wis2box_project_
sont utilisés pour stocker des données persistantes pour les différents services de la pile logicielle wis2box.
wis2box API
Le wis2box contient une API (Interface de Programmation d'Applications) qui fournit un accès aux données et des processus pour la visualisation interactive, la transformation des données et leur publication.
Ouvrez un nouvel onglet et accédez à la page http://YOUR-HOST/oapi
.
Ceci est la page d'accueil de l'API wis2box (exécutée via le conteneur wis2box-api).
Question
Quelles collections sont actuellement disponibles ?
Cliquez pour révéler la réponse
Pour voir les collections actuellement disponibles via l'API, cliquez sur View the collections in this service
:
Les collections suivantes sont actuellement disponibles :
- Stations
- Notifications de données
- Métadonnées de découverte
Question
Combien de notifications de données ont été publiées ?
Cliquez pour révéler la réponse
Cliquez sur "Data notifications", puis cliquez sur Browse through the items of "Data Notifications"
.
Vous noterez que la page indique "No items" car aucune notification de données n'a encore été publiée.
wis2box webapp
Ouvrez un navigateur web et visitez la page http://YOUR-HOST/wis2box-webapp
.
Vous verrez une fenêtre contextuelle demandant votre nom d'utilisateur et votre mot de passe. Utilisez le nom d'utilisateur par défaut wis2box-user
et le WIS2BOX_WEBAPP_PASSWORD
défini dans le fichier wis2box.env
, puis cliquez sur "Sign in" :
Note
Vérifiez votre fichier wis2box.env pour la valeur de votre WIS2BOX_WEBAPP_PASSWORD. Vous pouvez utiliser la commande suivante pour vérifier la valeur de cette variable d'environnement :
cat ~/wis2box/wis2box.env | grep WIS2BOX_WEBAPP_PASSWORD
Une fois connecté, déplacez votre souris vers le menu à gauche pour voir les options disponibles dans l'application web wis2box :
Ceci est l'application web wis2box qui vous permet d'interagir avec votre wis2box :
- créer et gérer des ensembles de données
- mettre à jour/examiner les métadonnées de vos stations
- télécharger des observations manuelles à l'aide du formulaire synop FM-12
- surveiller les notifications publiées sur votre wis2box-broker
Nous utiliserons cette application web dans une session ultérieure.
wis2box-broker
Ouvrez le MQTT Explorer sur votre ordinateur et préparez une nouvelle connexion pour vous connecter à votre broker (exécuté via le conteneur wis2box-broker).
Cliquez sur +
pour ajouter une nouvelle connexion :
Vous pouvez cliquer sur le bouton 'ADVANCED' et vérifier que vous êtes abonné aux sujets suivants :
#
$SYS/#
Note
Le sujet #
est un abonnement générique qui s'abonne à tous les sujets publiés sur le broker.
Les messages publiés sous le sujet $SYS
sont des messages système publiés par le service mosquitto lui-même.
Utilisez les détails de connexion suivants, en veillant à remplacer la valeur de <your-host>
par votre nom d'hôte et <WIS2BOX_BROKER_PASSWORD>
par la valeur de votre fichier wis2box.env
:
- Protocole : mqtt://
- Hôte :
<your-host>
- Port : 1883
- Nom d'utilisateur : wis2box
- Mot de passe :
<WIS2BOX_BROKER_PASSWORD>
Note
Vous pouvez vérifier votre fichier wis2box.env pour la valeur de votre WIS2BOX_BROKER_PASSWORD. Vous pouvez utiliser la commande suivante pour vérifier la valeur de cette variable d'environnement :
cat ~/wis2box/wis2box.env | grep WIS2BOX_BROKER_PASSWORD
Notez qu'il s'agit de votre mot de passe de broker interne, le Global Broker utilisera des identifiants différents (en lecture seule) pour s'abonner à votre broker. Ne partagez jamais ce mot de passe avec quiconque.
Assurez-vous de cliquer sur "SAVE" pour enregistrer les détails de votre connexion.
Puis cliquez sur "CONNECT" pour vous connecter à votre wis2box-broker.
Une fois connecté, vérifiez que les statistiques internes de mosquitto sont publiées par votre broker sous le sujet $SYS
:
Gardez le MQTT Explorer ouvert, car nous l'utiliserons pour surveiller les messages publiés sur le broker.
Conclusion
Félicitations !
Lors de cette session pratique, vous avez appris à :
- exécuter le script
wis2box-create-config.py
pour créer la configuration initiale - démarrer wis2box et vérifier le statut de ses composants
- accéder à wis2box-webapp et wis2box-API dans un navigateur
- vous connecter au broker MQTT sur votre machine virtuelle étudiante à l'aide de MQTT Explorer