new_service.md



Versionnage d'un nouveau service
L'idée de ce dépôt est de rendre nos services indépendants des machines virtuelles sur lesquels ils sont lancés, c'est-à-dire qu'à partir de ce dépôt, on devrait pouvoir remonter sans aucun problème un service sur une machine quelconque (sauf les données, bien sûr).
Cette page donne quelques pistes pour versionner un nouveau service sur ce dépôt.
On pourra partir du dossier template comme base.
Pour le contenu des fichiers Dockerfile et docker-compose.yml, on se réferera au guide des bonnes pratiques en cas de doute.

Choix des fichiers à versionner
Pour savoir si vous avez versionné tout les fichiers nécessaires, posez-vous la question suivante :

Si je fais un git pull puis un docker-compose up -d, est-ce-que mon service démarre correctement ?

Si oui, vous avez versionné les fichiers nécessaires. Si non, il faut remédier au problème. La seule exception concerne les opérations nécessaires pour créer les secrets (voir plus bas).

Fichiers nécessaires
Pour chaque service, on aura au moins :

Un README.md, qui explique de quoi il s'agit, comment lancer le service, comment le mettre à jour, etc. On pourra s'inspirer des services existants et du template.
Un docker-compose.yml, qui permet de lancer le service sur les machines de Picasoft. Les images utilisées doivent toujours avoir un tag de version précis (voir bonnes pratiques).


Image personnalisée
Si on utilise une image construite par nos soins, il faut rajouter :

Un ou plusieurs Dockerfile, qui permet(tent) de construire l'image.
Un CHANGELOG.md, qui indique les modifications effectuées au fil des versions.

Le Dockerfile peut contenir des directives COPY pour ajouter des fichiers à l'image. S'il s'agit d'un ou deux fichiers de configuration, ou d'un entrypoint, aucun souci pour le versionner sur ce dépôt. S'il s'agit de code à proprement parler, il est préférable de créer un dépôt spécifique qui contiendra le code du service, et de faire un git pull dans le Dockerfile (ou d'utiliser un sous-module Git).
En effet, ce dépôt n'est pas voué à contenir le code des services, mais simplement les fichiers nécessaires pour construire l'image, configurer et lancer le service.

Fichiers de configuration
Il est préférable de versionner la configuration du service sur ce dépôt, pour pouvoir relancer rapidement le service sur une machine quelconque sans devoir récupérer la configuration sur l'ancienne machine.
Cependant, si la configuration est souvent modifiée via l'interface d'administration du service, il est préférable de ne pas la versionner. Par exemple, Mattermost utilise un fichier config.json, mais on le modifie essentiellement à travers la Console Administrateur (interface graphique). Versionner ce fichier obligerait à modifier la configuration "à la main", puis à redémarrer Mattermost à chaque changement de paramètre.
Par contre, Etherpad utilise un fichier config.json qui n'est pas modifiable via une interface graphique, et qui est pris en compte uniquement au démarrage. C'est donc un bon fichier à versionner.
La rule of thumb est donc la suivante : on versionnera tous les fichiers qui ne sont pas modifiés dynamiquement quand le service est lancé.

Cas particuliers
Certaines images officielles demandent d'effectuer des opérations manuellement avant de les lancer (initialisation de base de données, etc).
Dans ce cas, on pourra créer un entrypoint qui remplace l'officiel et qui effectue ces opérations si jamais le service est lancé pour la première fois, puis qui lance le service normalement. On pourra marquer le fait qu'un service a déjà été initialisé en créant un fichier "marqueur" dans un volume. Voir Plume pour un exemple.
De manière générale, on hésitera pas à faire un entrypoint personnalisé si celui de l'image officielle ne suffit pas à nos besoins et qu'on ne peut pas configurer le service comme on le veut grâce aux variables d'environnement.

Gestion des secrets
Un service a souvent besoin de secrets pour démarrer. Par secrets, on entend souvent mot de passe, ou clé privée.
En général, les secrets sont configurés via des variables d'environnement. Quand c'est le cas, on créera un dossier secrets, puis des fichiers en .secrets.example qui contiennent une variable d'environnement par ligne. Voir les services existants pour un exemple.
Quand le service demande les secrets en clair dans un fichier de configuration, et qu'on ne peut pas faire référence aux variables d'environnement dans le fichier, on gardera le système des variables d'environnement et on remplacera l'entrypoint pour injecter les variables dans le fichier de configuration.
On trouvera un exemple dans pica-metrics-bot, où l'on voit que le fichier de configuration contient des marqueurs (INFLUXDB_USER par exemple), qui sont remplacés au démarrage du service par les valeurs des variables d'environnement correspondantes.