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](../template) comme base.

Pour le contenu des fichiers `Dockerfile` et `docker-compose.yml`, on se réferera au [guide des bonnes pratiques](./guide_bonnes_pratiques.md) 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](../pica-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](../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.