technique:tech_team:etherpad

Différences

Ci-dessous, les différences entre deux révisions de la page.

Lien vers cette vue comparative

Les deux révisions précédentes Révision précédente
Prochaine révision		 Révision précédente
technique:tech_team:etherpad [2021/12/19 19:44] – qduchemitechnique:tech_team:etherpad [2021/12/19 22:34] (Version actuelle) – qduchemi
Ligne 1: Ligne 1:
 +{{indexmenu_n>40}}
 +## Comment on met à jour Etherpad ? Et Git, c'est quoi ?
 +
 +Des services libres c’est bien, des services libres à jour c’est mieux.
 +
 +À ce stade, tu sais quasiment tout faire sur l'infrastructure de Picasoft ! Tu sais accéder aux machines via SSH, construire des images Docker, tu sais utiliser Compose pour orchestrer le lancement des conteneurs, et tu sais utiliser Traefik pour exposer un service sur le web avec une URL en `picasoft.net` !
 +
 +La suite de l'histoire, c'est d'apprendre à mettre à jour les services de Picasoft, en utilisant les outils que tu connais déjà.
 +
 +Dans cette page, on prend pour exemple la mise à jour d'Etherpad. 
 +
 +### Questions introductives
 +
 +<bootnote question> 
 +Pourquoi faire des mises à jour ?
 +</bootnote>
 +
 +Derrière un service il y a un logiciel qui fonctionne grâce à du code fait par des humains, les humains et donc les logiciels ne sont pas parfaits. On peut choisir d’ajouter des fonctionnalités, changer la manière de faire, optimiser, corriger des comportements jugés anormaux ou encore corriger des failles de sécurité plus ou moins importantes. En ce sens, même si cette tâche est rébarbative, il est important de mettre à jour les services.
 +
 +<bootnote question>
 +Comment on sait qu'il y a des mises à jour à faire ?
 +</bootnote>
 +
 +Un bot dans le canal [Alertes Techniques](https://team.picasoft.net/picasoft/channels/alertes-techniques) de l'équipe Mattermost de Picasoft, [[technique:adminsys:secu:services_updates|développé par Picasoft]], s’occupe de vérifier l’existence de nouvelles versions des différents services et envoie un message lorsqu’une nouvelle version existe. 
 +
 +Alternativement, on peut aussi passer sur chaque service pour vérifier sa version et comparer aux nouvelles versions.
 +
 +<bootnote question>Mais comment on connaît les versions des services ? Et comment on va voir s'il y a eu une mise à jour ? Et pourquoi est-ce-que les gens sont gênés quand ils disent bonjour au lieu de bonsoir ?</bootnote>
 +
 +Pour répondre à cette question, il faut faire un petit détour pour comprendre [[technique:docker:picasoft:dockerfiles|comment Picasoft gère les fichiers de configuration de ses services]].
 +
 +La configuration des services est gérée avec Git, un outil de gestion de versions de fichiers. Git mériterait une formation entière, alors on va seulement aborder la question en simplifiant, et ça suffira amplement pour l'utiliser.
 +
 +<bootnote web>
 +Tous les services Picasoft sont gérés sur **Gitlab** à cette adresse : https://gitlab.utc.fr/picasoft/projets/services
 +
 +Vas y faire un tour ! :-D
 +</bootnote>
 +
 +### Une brève introduction à Git et Gitlab
 +
 +<bootnote>
 +
 +Gitlab est une **forge** Git : un endroit où on stocke des documents, conçu pour la collaboration. L'idée est de donner des outils aux adminsys/développeur·ses/écrivain·es/etc pour collaborer en se basant sur Git.
 +
 +* Git permet de travailler à plusieurs sur des fichiers et d'en maintenir un **historique des modifications**.
 +* Gitlab permet de collaborer autour des documents gérés par Git : poser des questions, proposer des modifications, reporter des erreurs... et centraliser ces documents.
 +
 +</bootnote>
 +
 +Regardons le [dossier des services sur Gitlab](https://gitlab.utc.fr/picasoft/projets/services) : 
 +
 +{{ :technique:tech_team:gitlab.png |}}
 +
 +Comment tu peux le constater, il y a un « dossier » par service :
 +
 +* Chaque dossier est appelé **dépôt**. Chaque dépôt est complètement **indépendant** des autres.
 +* Chaque dépôt contient les fichiers nécessaires pour lancer le service en question.
 +* Les dépôts peuvent être **clonés** sur les machines. Cloné, ça veut dire copié en gardant un lien vers Gitlab.
 +
 +Alors concrètement, pour Traefik qui tourne sur toutes les machines, ça ressemble à quoi ?
 +
 +{{ :technique:tech_team:git_clones_1.png |}}
 +
 +Par convention, on clone les dépôts sur les machines dans `/DATA/docker/services`. Chaque machine a donc un dossier `/DATA/docker/services/traefik` qui est une copie du dépôt Traefik de Gitlab.
 +
 +<bootnote>Bon, donne nous un exemple ! C'est quoi l'intérêt ?</bootnote>
 +
 +<bootnote important>
 +Git permet de **réutiliser le travail**. D'une part, le fait de centraliser la configuration sur un dépôt public permet à des gens extérieurs à Picasoft de s'inspirer (plutôt que d'avoir les fichiers de configuration uniquement sur les machines), et d'autre part de **partager** les fichiers de configuration entre les machines plutôt que de **refaire** plusieurs fois le travail.</bootnote>
 +
 +Un exemple ?
 +
 +Imagine que je mette à jour Traefik dans une nouvelle version sur `pica01`. Super, j'ai modifié des fichiers (au moins le fichier Compose, pour indiquer d'utiliser une nouvelle version de l'image), je suis donc en **avance** par rapport aux fichiers qui se trouvent sur Gitlab et les autres machines.
 +
 +{{ :technique:tech_team:git_clones_2.png |}}
 +
 +Grâce à Git, je vais pouvoir **pousser** mes modifications sur le Gitlab :
 +
 +{{ :technique:tech_team:git_clones_3.png |}}
 +
 +Et là, si je veux mettre à jour Traefik sur `pica02` et `monitoring`, pas besoin de refaire les modifications, il me suffit de **tirer** les modifications depuis Gitlab :
 +
 +{{ :technique:tech_team:git_clones_4.png |}}
 +
 +Avec Git, cette situation pourrait aussi se produire : deux personnes bossent sur Traefik sur deux machines différentes...
 +
 +{{ :technique:tech_team:git_clones_5.png |}}
 +
 +C'est un **conflit** : quelle version choisir au moment d'envoyer sur Gitlab ? Et bien Git est équipé pour résoudre ce genre de problèmes. Mais on en a déjà trop dit ! 
 +
 +Si tu as vaguement compris l'intérêt de Git jusque ici, on va voir maintenant en pratique comment l'utiliser pour les mises à jour.
 +
 +### C'est quoi les étapes pour mettre à jour Etherpad ?
 +
 +<bootnote web>Le dépôt Gitlab pour Etherpad est ici : https://gitlab.utc.fr/picasoft/projets/services/etherpad-yearly</bootnote>
 +
 +1. On va sur la **machine de test**.
 +2. On va dans `/DATA/docker/services` et on se synchronise avec le dépôt : si la copie locale n'existe pas, on **clone** le dépôt, sinon, on **tire** les modifications (s'il y en a).
 +3. On fait nos modifications et on teste que ça marche bien.
 +4. On les **pousse** sur le dépôt Gitlab : « tout le monde » peut en profiter.
 +5. On va sur la **machine de production**.
 +6. Dans `/DATA/docker/services`, on **tire** les modifications que l'on vient de pousser.
 +7. Et on lance le service! :-D
 +
 +<bootnote important>
 +La partie `3` dépend de chaque service et les opérations spécifiques sont détaillées dans la description Gitlab du service en question. Ici, on explique tout pour Etherpad!
 +</bootnote>
 +
 +<bootnote question>
 +Bon allez là, on y va ou quoi ?! ^_^
 +</bootnote>
 +
 +### Mise à jour et test de l'image
 +
 +#### Le commencement 
 +
 +Traditionnellement, on fait les tests sur la machine de test.
 +
 +```
 +$ ssh <ton login>@pica01-test.picasoft.net
 +```
 +
 +On se rend dans le dossier `/DATA/docker/services/etherpad-yearly` :
 +
 +```
 +$ cd /DATA/docker/services/etherpad-yearly
 +```
 +
 +<bootnote warning>
 +S'il n'existe pas, pas de panique, il suffit de cloner le dépôt. On se rend dans `/DATA/docker/services` et on utiliser la commande suivante :
 +
 +```
 +$ git clone https://gitlab.utc.fr/picasoft/projets/services/etherpad-yearly.git
 +```
 +
 +Cette URL se trouve sur le dépôt Gitlab d'Etherpad, en cliquant sur le bouton « Clone », partie HTTPS :
 +{{ :technique:tech_team:etherpad_clone.png |}}
 +</bootnote>
 +
 +Et là, première commande Git pour être sûr qu'on a la dernière version, qui est sur Gitlab - on **tire** les modifications :
 +
 +```
 +$ git pull
 +```
 +
 +#### C'est organisé comment ?
 +
 +```
 +$ tree
 +.
 +├── CHANGELOG.md
 +├── Dockerfile
 +├── entrypoint.sh
 +├── landing-page
 +│   └── ... (volontairement replié pour la lisibilité)
 +├── README.md
 +├── secrets
 +│   ├── etherpad-app.secrets.example
 +│   └── etherpad-db.secrets.example
 +└── settings.json
 +```
 +
 +On voit qu’il y a un fichier `Dockerfile` à la racine, il s’agit d’un bon indice que l’image du service est faite maison. Ce fichier va nous intéresser ici afin de construire une nouvelle image à la nouvelle version, c’est en effet le fichier qui contient la recette de cuisine d’une image.
 +
 +On remarque aussi le fichier `docker-compose.yml`, qui indique **comment** lancer l'image.
 +
 +#### Changer la version du logiciel
 +
 +On va donc éditer le `Dockerfile` ici. Pour des raisons pratiques la version utilisée est indiquée dans un argument qu’on peut ensuite réutiliser afin de n’avoir à la changer qu’une seule fois, aussi on la trouve généralement en début de fichier afin d’y avoir accès rapidement. Regardons le début du fichier :
 +
 +```
 +$ head -n 10 Dockerfile
 +FROM node:14-buster-slim as base
 +LABEL maintainer="quentinduchemin@tuta.io"
 +
 +ENV NODE_ENV=production
 +
 +FROM base as downloader
 +
 +ARG ETHERPAD_VERSION_BUILD=1.8.14
 +
 +RUN apt-get update && \
 +```
 +
 +On observe plusieurs instructions, dont `ARG ETHERPAD_VERSION_BUILD=1.8.14` qui indique le numéro de version du logiciel.
 +
 +Afin de passer à une version plus récente on va simplement changer la valeur `1.8.14` en `1.8.15` !
 +
 +<bootnote>Si tu lis la suite du `Dockerfile`, tu verras que `ETHERPAD_VERSION_BUILD` est utilisé dans l'URL de téléchargement, qui va récupérer l'archive avec le vrai code d'Etherpad, qui lui se trouve sur une forge nommée GitHub : https://github.com/ether/etherpad-lite/releases</bootnote>
 +
 +#### Changer le tag de l'image Compose 
 +
 +Maintenant que la recette de l’image est bien à jour, il ne faut pas oublier d’indiquer dans le fichier de configuration que l’on utilise une nouvelle version.
 +
 +Pour cela il faut modifier le tag de l’image (ce qui correspond au fait à un numéro de version dans notre cas) dans le fichier `docker-compose.yml`. C'est dans l'extrait qui suit :
 +
 +```yaml
 +app:
 +  image: registry.picasoft.net/pica-etherpad:1.8.14
 +  build: .
 +  container_name: etherpad_app
 +```
 +
 +On le passe en `1.8.15`. Essentiellement, ce qu'on est en train de dire à Compose c'est : « quand tu construiras l'image à partir du `Dockerfile`, tu l'appelleras `pica-etherpad:1.8.15` et c'est ensuite cette image que tu utiliseras pour lancer le service ».
 +
 +#### Et zéééééparti pour les tests!
 +
 +Alors, pour être honnête, il y a plein de choses à faire pour tester une image. Plein de petits détails chiants, un peu comme ton pull en laine qui gratte. Notamment :
 +
 +- Créer des faux « secrets », quand il y a besoin de mots de passe pour lancer une base de données de test
 +- Changer les URL `picasoft.net` en `test.picasoft.net`, puisque on est sur la machine de test
 +- Supprimer les anciennes données pour éviter des « faux bugs »...
 +
 +Bref ! On a fait un script qui fait tout ça pour toi. Il se trouve dans `/DATA/docker/services`, et il suffit de lui passer en argument le nom du dossier où tu veux lancer les tests :
 +
 +```
 +$ cd /DATA/docker/services
 +$ ./docker_test.sh etherpad-yearly
 +```
 +
 +Tu peux ignorer les warnings, tant que la construction de l'image se passe bien. À la fin, le conteneur devrait démarrer et t'afficher les journaux! Pour vérifier que tout fonctionne, il suffit d'aller sur `pad.test.picasoft.net` dans un navigateur.
 +
 +<bootnote warning>Le service peut mettre une bonne minute à démarrer après la construction de l'image, pas de panique :-D</bootnote>
 +
 +#### Pousser ses modifications
 +
 +Tout marche ? C'est parti pour la mise en production !
 +
 +Première chose : pousser l'image sur notre registre Docker. C'est un peu la même idée que Git : réutiliser l'image qu'on vient de construire, en production, plutôt que de la reconstruire. 
 +
 +<bootnote learn>Plus d'infos sur le registre [[technique:docker:general:mise_en_place_d_un_registry_docker|sur cette page]].</bootnote>
 +
 +```
 +$ docker-compose push
 +```
 +
 +<bootnote>
 +Si jamais on te dit que tu n'es pas connecté au registre, hop :
 +
 +```
 +$ docker login registry.picasoft.net
 +```
 +
 +Utilise les mêmes identifiants sur sur les machines.
 +</bootnote>
 +
 +Deuxième chose, on va pousser nos modifications de la configuration sur le Gitlab. On retourne dans le bon dossier...
 +
 +```
 +$ cd /DATA/docker/services/etherpad-yearly
 +```
 +
 +Tu peux vérifier les modifications que tu t'apprêtes à pousser :
 +
 +```
 +$ git diff
 +```
 +
 +Vérifie que les lignes en vert sont bien celles que tu as changées. Tu peux ensuite valider ces modifications et leur donner une description. L'idée, c'est de créer une sorte de point dans le temps où on pourra revenir si besoin, et qui permettra à tout le monde de voir les modifications effectuées (l'historique) :
 +
 +```
 +$ git commit -am "Mise à jour vers la version 1.8.15"
 +```
 +
 +<bootnote>
 +Si c'est la première fois que tu utilises Git sur cette machine, il va te demander ton nom et ton email. Pour ce faire...
 +
 +```
 +$ git config --global user.name "ton nom"
 +$ git config --global user.email "ton mail"
 +```
 +
 +Tu peux ensuite recommencer la commande `commit`.
 +</bootnote>
 +
 +Pour finir, tu peux pousser ces modifications sur Gitlab (les identifiants qu'on te demande sont ceux de l'UTC !) :
 +
 +```
 +$ git push
 +```
 +
 +### Mise en production - attention, chute de pierres.
 +
 +C'est parti pour le grand saut, la mise en production de notre image toute fraîche ! C'est presque comme pour les tests sauf qu'on a plus rien à construire, juste à récupérer notre travail. Alors on résume !
 +
 +#### Connexion sur la machine de production
 +
 +```
 +$ ssh <ton login>@pica02.picasoft.net
 +```
 +
 +<bootnote question>
 +Comment on sait que c'est sur `pica02` ?
 +</bootnote>
 +
 +L'expérience. ^_^
 +
 +Mais tu peux aussi regarder sur les [[technique:graph_services|graphes des services]]...
 +
 +#### On tire les modifications
 +
 +Dans le bon dossier :
 +
 +```
 +$ cd /DATA/docker/services/etherpad-yearly
 +```
 +
 +On récupère les modifications de Gitlab :
 +
 +```
 +$ git pull
 +```
 +
 +On récupère nos images :
 +
 +```
 +$ docker-compose pull
 +```
 +
 +Et enfin, on lance la nouvelle version !
 +
 +```
 +$ docker-compose up -d
 +$ docker-compose logs -f
 +```
 +
 +On regarde si tout va bien dans les journaux, on attend un peu et on consulte `pad.picasoft.net`. Si ça fonctionne, waouh, c'est bon ! Et sinon... direction l'équipe technique! ;-)