Install.md

Production régionalisée reproductible (PRR) Onde

Ce document décrit pas à pas l'installation et la mise à jour de l'outil PRR Onde. Ces opérations utilisent les services de la plateforme GitHub. Elles requièrent uniquement la création d'un compte sur cette plateforme.

Installation de l'outil

Prérequis : disposer d'un compte GitHub.

1. Se connecter à Github (https://github.com/)
2. Naviguer vers le dépôt GitHub de référence de l'outil, https://github.com/richaben/prr_onde
3. Cliquer sur le bouton Fork en haut à droite de la page d'accueil du dépôt. Cette action lance la copie du dépôt dans l'espace de l'utilisateur GitHub connecté.

Un formulaire de paramétrage du nouveau dépôt apparaît :

4. Décocher l'option Copy the master branch only et cliquer sur le bouton Create fork. Une fois la copie réalisée, le dépôt apparaît dans l'espace de travail de l'utilisateur connecté.

5. Cliquer sur le bouton Settings.

L'écran de paramétrage du dépôt apparaît :

6. Cliquer sur l'élément Code and automation > Pages pour afficher les paramètres du service Github Pages. Ce service permet d'associer un site web à un dépôt GitHub.

7. Dans la section Branch, sélectionner deploy et root puis cliquer sur le bouton Save Le dépôt dispose désormais d'un site web hébergé par GitHub Pages. L'url d'accès à ce site est de la forme https://{identifiant de l'utilisateur github}.github.io/PRR_ONDE/ (Exemple : https://ofb-nor.github.io/PRR_ONDE/).

8. Afficher de nouveau la page d'accueil du dépôt et cliquer sur le bouton de paramétrage du panneau About (bouton symbolisé par un engrenage à droite de l'écran).

Une fenêtre apparaît :

9. Renseigner le champ Website avec l'url du site web du dépôt (ou cocher sur Use your GitHub Pages website), puis cliquer sur le bouton Save changes. L'url doit désormais apparaître dans le panneau About sur la page d'accueil du dépôt.

10. Retourner dans Settings, puis cliquer sur l'élément Code and automation > Actions > General pour afficher les paramètres généraux du service Github Actions. Ce service permet d'automatiser l'exécution d'un traitement.

11. Dans la section Workflow permissions en bas de l'écran, sélectionner Read and write permissions, puis cliquer sur le bouton Save.

12. Cliquer sur l'élément Actions.

La fenêtre suivante apparaît :

13. Cliquer sur le bouton I understand my workflows, go ahead and enable them. La liste des traitements automatisés ou flux de travail (workflow en anglais) apparaît :

La liste comprend : - la synchronisation automatique des branches master et deploy après chaque mise à jour de l'outil ; - l'actualisation quotidienne du site web après chaque mise à jour des données Onde.

14. Cliquer sur l'item Script_R_ONDE_carto_auto. Le paramétrage de l'actualisation des données apparaît :

15. Cliquer sur le bouton Enable workflow pour activer le déclenchement automatique du traitement.

A ce stade, toute mise à jour de l'outil ou des données entraine une actualisation du site web.

Le contenu de la page, sa mise en forme et/ou la fréquence de son actualisation restent paramétrables.

16. Afficher la page d'accueil du dépôt et cliquer sur le script R _config.R à la racine du dépôt :

Le code R du script apparaît à l'écran :

17. Cliquer sur le bouton Edit this file et adapter le paramétrage à une région de France. Important : les codes de départements doivent être encadrés par des " et préfixés par 0 pour les départements dont le code est inférieur à 10.

18. Une fois le paramétrage renseigné, cliquer sur le bouton Commit changes

Une fenêtre apparaît :

19. Renseigner Adaptation du traitement à la région dans le champ Commit message et cliquer sur le bouton Commit changes. Une fois enregistré, le script réapparaît en lecture seule. Cette modification de code déclenche l'actualisation du site web. Il est alors possible de suivre l'avancement du traitement en cliquant sur le libellé du script de traitement :

Il est également possible de suivre chaque étape du traitement en cliquant de nouveau sur le libellé du script R :

Une fois le traitement terminé, il est possible de vérifier son résultat et sa durée :

20. En cas de succès, consulter le site web actualisé en activant le lien depuis la page d'accueil du dépôt :

Mise à jour de l'outil

1. Se connecter à GitHub
2. Afficher la page d'accueil du dépôt PRR_ONDE. Un message This branch is ..., **x commits behind richaben:master**doit indiquer la nécessité d'une mise à jour de l'outil.

3. Cliquer sur le bouton Sync fork. Une fenêtre de validation apparaît.
4. Cliquer sur le bouton Update branch .

La mise à jour de l'outil est déclenchée, suivie par l'actualisation du site web. Une fois les traitements terminés, les modifications sont reflétées dans la nouvelle version du site web.

Enregistrement d'une demande d'amélioration de l'outil

1. Se connecter à GitHub
2. Naviguer vers le dépôt GitHub de référence de l'outil, https://github.com/richaben/prr_onde . Important : pour centraliser l'ensemble des demandes sont à faire sur le dépôt de référence, et ne doivent pas être enregistrées dans les dépôts régionaux résultant d'une copie du dépôt de référence !
3. Cliquer sur l'élément Issues

La liste des demandes apparaît.

4. Cliquer sur le bouton New issue

Un formulaire de saisie de la demande apparaît :

5. Renseigner un titre concis et une description de la demande, puis cliquer sur le bouton Submit new issue

Un dialogue s'engage alors avec l'équipe en charge du développement de l'outil. Ce dialogue peut conduire à plusieurs échanges sur un fil de discusssion associé à la demande (issue)

6. Une fois la demande traitée, renseigner un dernier message de validation et cliquer sur le bouton Close with comment

Actualisation manuelle du site web

En cas d'erreur sur les traitements automatiques, il est possible de relancer manuellement l'actualisation du site web en suivant les étapes suivantes :

1. Se connecter à GitHub
2. Afficher la page d'accueil du dépôt régional PRR_ONDE
3. Cliquer sur l'élément Actions
4. Cliquer sur le script d'actualisation du site web (nommé Script_R_ONDE_carto_auto)
5. Cliquer sur le bouton Run workflow. Une fenêtre apparaît.
6. Sélectionner la branche deploy puis cliquer sur le bouton Run workflow.

Désinstallation de l'outil

1. Se connecter à GitHub
2. Afficher la page d'accueil du dépôt régional PRR_ONDE
3. Cliquer sur l'élément Settings La page des paramètres généraux du dépôt régional apparaît.
4. En bas de page, dans la section Danger Zone, cliquer sur le bouton Delete this repository

Une 1êr écran de confirmation apparaît :

5. Cliquer sur le bouton I want to delete this repository Une 2nd écran de confirmation apparaît :

6. Cliquer sur le bouton I have read and understand these effects Un 3ème écran de confirmation apparaît :

7. Renseigner le libellé du dépôt régional comme indiqué et cliquer sur le bouton Delete this repository Un dernier écran de confirmation apparaît :

8. Renseigner votre mot de passe GitHub puis cliquer sur le bouton Confirm La suppression du dépôt régional est déclenchée. Une fois l'opération réalisée, le dépôt n'apparaît plus dans la liste des dépôts de l'utilisateur GitHub.