Mettre à jour un service ou sa configuration

Attention:

Prérequis : les articles de cette section.

Note:

Ces explications ne valent que pour un service qui est déjà en production et que l’on souhaite mettre à jour.

Tous les fichiers permettant de paramétrer les conteneurs Docker d’un service sont versionnés sur son dépôt, [ici(https://gitlab.utc.fr/picasoft/projets/services) (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.

Attention:

Toute modification apportées à n’importe quel fichier versionné doit être poussée sur le 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.

Il pourrait être 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.

Important:

Les instructions spécifiques de mise à jour de chaque service se trouvent dans le README de chaque dossier. Pensez à y jeter un coup d’oeil.

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:10postgres: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.

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 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).

  • technique/docker/picasoft/update.txt
  • de ppom