Définir des variables d’environnement¶
Pour quoi faire ?¶
Lorsque l’on réalise des cartes dans certains environnements, et que l’on utilise le processus suivant :
- Développement de la carte en local ==>
localhost:xxxx/mviewer
- Passage sur un environnement de test type recette / pré-pod ==>
https://map.recette.fr/mviewer
- Déploiement final vers l’environnement de production ===>
https://map.fr/mviewer
Pour chacun de ces environnements, l’URL change. On doit donc modifier à chaque étape les chemins et URLs des couches dans les XML, customlayers, extensions, customcontrol, etc…
La modification est manuelle et il y a souvent des erreurs. C’est aussi clairement fastidieux pour une carte contenant beaucoup de ressources ou alors lorsque le nombre d’applications à migrer est important.
Concept¶
Pour faciliter cette transition, un système basé sur un/des fichier(s) .json
permet de définir des variables d’environnement.
A noter que par défaut, un fichier apps/settings.json
est fourni.
Les variables d’environnement qui peuvent être contenues dans ce type de fichier sont principalement des liens pour accéder aux ressources des couches. Ils sont donc propres à chaque environnement.
Exemple de variable définie dans apps/settings.json
sur un environnement de recette :
{
"fqdn": "map.recette.fr"
}
La même variable définie dans apps/settings.json
sur un environnement de production :
{
"fqdn": "map.fr"
}
Ainsi en définissant des variables communes aux différents environnements mais dont seule la valeur change d’un environnement à l’autre, il n’est plus nécessaire de changer l’URL des ressources à la main lors du passage d’un fichier de la préproduction à la production.
Comment faire ?¶
1. Créer un fichier définissant les variables
Variables globales
Dans le répertoire /apps
, modifiez (ou créer si inexistant) le fichié settings.json
et définissez une ou plusieurs variable(s) comme ci-dessous :
{
"fqdn": https://map.recette.fr
}
Note
Les variables définies dans le fichier .json
pourront être appelées dans l’ensemble des applications disponible dans le répertoire /apps
.
Variables spécifiques à une application
Si l’on souhaite définir des variables pour une application spécifique nommée MaCarte.xml
, il est possible de créer un fichier d’environnement dédié à cette application.
Ainsi, dans le même répertoire que l’application, créez un nouveau fichier nommé MaCarte.json
(le fichier d’environnement doit avoir le même nom que le fichier de configuration .XML).
Dans ce fichier, définissez une ou plusieurs variable(s) comme ci-dessous comme on le ferez avec le fichier apps/settings.json
:
{
"fqdnMaCarte": https://MaCarte.recette.fr
}
Avertissement
Les variables définies dans ce fichier ne pourront être utilisées que dans l’application associée, ici MaCarte.xml
Comportement des fichiers d’environnement
- On utilise les variables par défaut du fichier
apps/setings.json
- Si aucun fichier
.json
n’existe, alors le système actuel et classique fonctionnera afin de lire simplement le XML sans chercher à remplacer des URLs. - Si le code détecte un fichier
.json
du même nom que la config (et au même endroit) alors le fichierapps/settings.json
est surchargé par le fichier.json
qui accompagne la config (doncmaConfig.json
surchage et remplace les valeurs communes deapps/settings.json
) - On peut utiliser l’URL pour préciser le fichier
.json
à utiliser (e.g &env=apps/test/test.json
) afin de remplacer le fichierapps/settings.json
par le fichier passé dans l’URL - Les
.json
sont ignorés par git via le.gitignore
pour ne pas écraser les fichiers selon les environnement et ne pas avoir à le réécrire à chaque mise à jour de son projet Git
2. Mobiliser les variables d’environnement dans le fichier de configuration
Pour appeler les variables dans le fichier de configuration .XML, on utilise la syntaxe Mustache en configurant une couche comme ci-dessous :
1 | <layer url="{{fqdn}}/geoserver/rb/wms"/>
|
Lors de l’appel du XML au chargement de la carte, le code remplacera l’expression {{fqdn}}
par https://ma.recette.fr
pour obtenir un XML avec les URLs correctes. On aura alors pour notre <layer>
dans le XML final :
1 | <layer url="https://ma.recette.fr/geoserver/rb/wms" />
|
Cette syntaxe peut être utilisée pour l’ensemble des ressources mobilisées dans le fichier de configuration .XML telles que des styles, des images, des templates, etc …
3. Mobiliser les variables d’environnement dans un customlayer
Il est également possible d’appeler les variables d’environnement dans un fichier du type customlayer en configurant votre fichier moncustomlayer.js
comme ci-dessous :
1 2 3 4 5 6 7 8 | const url = `https://${mviewer.env?.fqdn}/geoserver/rb/wfs...`;
let layer = new ol.layer.Vector({
source: new ol.source.Vector({
url: url,
format: new ol.format.GeoJSON()
})
});
|
Avertissement
Pour que cette syntaxe fonctionne, vous devez utiliser des littéraux de gabarits ` ` (accent grave au lieu des apostrophes doubles ou simples) pour délimiter l’url.
Cas d’usage¶
Exemple 1
J’ai une application sur une préprod qui a le domaine : map.recette.fr
Ma carte mviewer utilise un flux WMS de préprod et un customLayer avec un flux WFS de préprod.
Je souhaite pouvoir changer facilement vers une plateforme de production qui a le domaine : map.fr
Alors je saisi sur ma recette apps/settings.json
une variable aléatoire que j’appel fqdn
:
{
"fqdn": "map.recette.fr"
}
et je saisi sur mon serveur de production dans apps/settings.json
la même variable avec la valeur qui convient :
{
"fqdn": "map.fr"
}
Dans mon config XML j’utilise alors pour mon WMS la syntaxe Mustache {{fqdn}}
:
1 | <layer url="{{fqdn}}/geoserver/rb/wms"/>
|
Dans mon customLayer je peux par ailleurs appeler directement l’url WFS via :
1 | const url = `https://${mviewer.env?.fqdn}/geoserver/rb/wfs...`;
|
Exemple 2
Prenom ces 3 fichiers et le contenu associé :
apps/settings.json
{
"version": "3.8.1-snapshot"
}
demo/test/test.json
{
"fqdn": "https://fqdn.com"
}
demo/test/test.xml
En chargeant la carte mviewer pour la configuration demo/test/test.xml
, je peux déjà ouvrir la console et voir mes variables et valeurs associés en saisissant en JavaScript mviewer.env
afin de les consulter :
{
"fqdn": "https://fqdn.com",
"version": "3.8.1-snapshot"
}
On comprend là que mviewer.env
permet d’accéder aux variables depuis un customlayer, le coeur mviewer ou une extension.
Si je souhaite à présent remplacer la valeur de la variable version
fournie dans mon fichier apps/settings.json
par défaut, je n’aurai qu’à l’ajouter avec la nouvelle valeur (ex: inconnu
) dans le fichier demo/test/test.json
:
{
"fqdn": "https://fqdn.com",
"version": "inconnu"
}
On pourra ici encore obtenir via la console du navigateur la liste des variables et les valeurs avec le code JavaScript mviewer.env
:
{
"fqdn": "https://fqdn.com",
"version": "inconnu"
}