update_and_test.md

Mise à jour et test d'un service

Cette page indique les différentes manières de mettre à jour un service et de le tester, avant sa mise en production.

On peut vouloir mettre à jour :

• Le service (e.g. changer un numéro de version dans le Dockerfile),
• La configuration (éditer un fichier quelconque),
• La configuration des volumes (e.g. changer le point de montage du Docker Compose),
• etc.

Dans tous les cas, les modifications apportées à n'importe quel fichier de ce dépôt doivent être poussées sur ce dépôt. Vous pouvez effectuer les modifications sur votre machine ou sur une machine de Picasoft, du moment qu'elles sont synchronisées avec le dépôt.

Comment mettre à jour un service ?

Il est pertinent de créer une branche avant chaque mise à jour où vous n'êtes pas sûr des modifications, et ne de fusionner dans master que lorsque les tests ont été effectués.

Mise à jour de la configuration

On appelle configuration tout ce qui ne nécessite pas de reconstruire une image :

• Modification du docker-compose.yml (environnement, point de montage, tag d'une image officielle...)
• Modification d'un fichier de configuration
• Modification d'une page web d'accueil
• etc.

Il suffit de mettre à jour les fichiers souhaitées, éventuellement de signaler les changements à l'équipe ou en commentaire, puis de synchroniser avec le dépôt.

Si vous mettez à jour le tag d'une image officielle (e.g postgres:10 → postgres:12), lisez au préalable la documentation de mise à jour ! Certaines nécessitent des interventions manuelles, et le README du service le précise en général.

Toute image indiquée dans le fichier Compose doit avoir un tag (e.g postgres:12 et pas postgres). N'utilisez jamais un tag vide (équivalent à latest).

Mise à jour d'une image maison

Apportez vos modifications au Dockerfile (ajout d'un paquet...). Vous pouvez travailler en local et tester l'image sur votre machine si vous voulez.

Si le code du service à copier dans l'image est intégré au dépôt par un submodule, on lancera la commande suivante pour le mettre à jour à la dernière version. Voir la documentation des submodules pour utiliser un tag ou une branche spécifique.

git submodule update --recursive --remote <dossier du service>

Synchronisez ensuite le tout avec le dépôt (git commit, git push...).

Comment tester le service mis à jour ?

Avant de mettre en production un service, il faut s'assurer que la mise à jour n'a rien cassé. Même si vous avez testé la nouvelle image sur votre machine, il faut également la tester sur l'infrastructure de Picasoft, en particulier parce que les services ont souvent besoin de Traefik pour fonctionner.

Pour ce faire, rendez-vous sur pica01-test, dans le clone du dépôt (usuellement /DATA/docker/dockerfiles).

Attention, notez que parfois il y a des problèmes indépendants du service quand celui-ci est accessible via Traefik :

• Tant que le HEALTHCHECK n'est pas passé, Traefik ne route pas vers le service (on vérifiera que le conteneur est noté healthy dans la sortie de docker ps)
• Parfois, Traefik ne route pas vers le service et renvoie un Gateway Timeout. Un docker restart traefik résoud le problème s'il vient de là.

Automatiquement

Le script docker_test.sh permet d'automatiser toutes les étapes pour tester un service et s'assurer qu'il fonctionne bien indépendamment des données précédentes, qui auraient été conservées dans un volume, par exemple. Il permet aussi de remplacer toutes les URL de production par des URL de test.

Il a le désavantage qu'on comprend moins ce que l'on fait. Pour s'en servir, lancez :

$ ./docker_test.sh <nom du dossier, e.g. pica-mattermost>

Vérifiez que les logs ne produisent aucune erreur et que le service fonctionne bien sur l'infrastructure de test, en y accédant via son URL par exemple (attention : remplacer picasoft.net par test.picasoft.net dans votre navigateur).

Manuellement

Si vous voulez tester le service "à la main", ou que le script ne fonctionne pas pour vous, ou pour toute autre raison, suivez ces étapes :

Synchronisation

Synchronisez vous exactement avec le dépôt :

# master ou votre branche perso
git checkout <votre branche>
git pull

Remise à zéro

Si le service était déjà lancé sur la machine de test, éteignez-le et remettez les volumes à 0 :

docker-compose down -v

Si des volumes sont déclarés comme external dans le fichier Compose, supprimez-les manuellement :

docker volume rm <volume>

Construction des images

Si le service utilise des images "maison", il faut les construire. Si le fichier Compose est bien fait, il suffit de lancer :

docker-compose build

Sinon, il faut construire les images à la main. À répéter pour chaque image maison du service concerné :

docker build [-f <Dockerfile>] -t <image> <context>

• Si le Dockerfile a un nom différent, on utilise le switch -f
• <image> doit avoir rigoureusement la valeur de la directive image du fichier Compose
• <context> est le contexte que reçoit Docker pour construire l'image (base pour copier les fichiers). En général, c'est le dossier du service (donc ., puisqu'on est dedans).

Remplacement des URLs

Si nécessaire. Certains services ne sont pas accessibles depuis Internet.

Remplacez les URL de production (.picasoft.net) par des URL de tests (.test.picasoft.net), sauf dans le nom de l'image :

• Si le service utilise Traefik, voir du côté de traefik.http.services.<service>.loadbalancer.server.port dans le fichier Compose
• Si le service utilise des fichiers de configuration, remplacez les références aux URL...

Créer les fichiers d'example

Copier tous les .secrets.example en .secrets.

Récupérer les nouvelles images

Si le service utilise des images officielles, on s'assure qu'elles sont bien à jour avec la commande :

docker-compose pull

Lancer le service

docker-compose up -d

Vérifier que tout fonctionne bien

docker-compose logs -f

On constate l'absence d'erreurs dans les logs, et si le service est accessible via Internet, on regarde que tout fonctionne bien depuis l'URL de test.

En cas de problème

À partir de là, c'est carte blanche : on peut modifier la configuration, le Dockerfile, reconstruire les images, etc. L'infrastructure de test est un bac à sable.