Mettre à jour un service ou sa configuration

Tous les fichiers permettant de paramétrer les conteneurs Docker et les services sont versionnés sur le dépôt dockerfiles (voir gestion des services).

On peut vouloir mettre à jour :

• Le service (e.g. passer d’une version X à une version Y),
• La configuration du service (e.g. changer un paramètre dans un fichier config.json),
• La configuration des volumes (e.g. changer le point de montage du Docker Compose),
• etc.

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.

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.

On appelle configuration tout ce qui ne nécessite pas de reconstruire l’image Docker, par exemple :

• Modification du docker-compose.yml (environnement, point de montage, changement du tag d’une image officielle…). Par exemple, Wekan est mis à jour uniquement en changeant le numéro de version dans le fichier Compose, car il utilise une image déjà construite.
• Modification d’un fichier de configuration monté dans le conteneur. Par exemple, Etherpad utilise un fichier settings.json qui est monté dans l’image à chaque démarrage.
• etc.

Il suffit de mettre à jour les fichiers souhaités, éventuellement de signaler les changements à l’équipe ou en commentaire, puis de pousser les modifications sur 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).

Certaines modifications nécessitent de reconstruire l’image, par exemple :

• Changement d’un numéro de version dans une archive téléchargée dans le Dockerfile. Par exemple, Mattermost indique le numéro de version de la release à téléchargement directement dans le Dockerfile.
• Ajout d’un paquet. Par exemple, on pourrait avoir besoin de rajouter un module PHP pour une nouvelle extension directement dans le Dockerfile.
• Changement d’un script d’initialisation copié dans le Dockerfile. Par exemple, le script d'initialisation de Plume effectue diverses opérations que l’on pourrait vouloir compléter, et ce script est copié directement dans le Dockerfile.
• etc.

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

Vous pouvez travailler en local et tester l’image sur votre machine si vous voulez. Il y a quelques modifications supplémentaires à apporter. Comme on construit une nouvelle version de l’image, il faut modifier le tag dans le fichier Compose pour que l’image construite soit différenciée des précédentes.

• Si on met à jour un service (version X → version Y), on passera le tag du fichier Compose de X à Y.
• Si on met juste à jour un fichier “maison” ou une configuration intégrée dans l’image, mais qu’on ne change pas la version du logiciel, on pourra ajouter au tag quelque chose comme -Z, de sorte que le tag deviennent registry.picasoft.net/pica-<service>:vX-Z.

Dans tous les cas, on modifiera ou on créera le fichier CHANGELOG.md pour décrire les modifications apportées à l’image.

Une fois que toutes ces modifications sont poussées sur le dépôt, il faut aussi pousser la nouvelle version de l’image sur le registre de production.

Le plus simple est de se rendre sur la machine de test (qui est sans doute plus puissante que votre machine et se trouve sur le même réseau que le registre de production), de se synchroniser avec le dépôt, de construire l’image, et de la pousser. Ça ressemble à ça :

snippet.bash

$ ssh login@pica01-test.picasoft.net
$ cd /DATA/docker/dockerfiles
$ git pull
# Si vous avez travaillé sur une branche spécifique
$ git checkout <votre branche>
$ cd pica-<service>
# Construire la nouvelle image et la tagger
# avec le nom indiqué dans le fichier Compsoe
$ docker-compose build
# Pousser l'image construite sur registry.picasoft.net
$ docker-compose push

Une fois arrivé à ce stade, votre nouvelle version du service est prête à être déployée depuis n’importe quelle machine de Picasoft. La prochaine étape est de tester la modification que vous avez apportée, sauf si elle est vraiment minime (exemple : changement marginal d’un paramètre de configuration).