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](../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 :

```bash
$ ./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 :

```bash
# 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 :

```bash
docker-compose down -v
```

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

```bash
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 :

```bash
docker-compose build
```

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

```bash
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 :

```bash
docker-compose pull
```

#### Lancer le service

```bash
docker-compose up -d
```

#### Vérifier que tout fonctionne bien

```bash
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.

Si jamais les modifications ont permis de résoudre le problème, on les commit et on les synchronise avec le dépôt.

### Revenir à l'état initial

On se resynchronise avec l'état du dépôt en enlevant toutes les modifications induites par les tests.
```bash
git reset --hard
```

## Que faire après les tests ?

Une fois qu'on est convaincu que la nouvelle version du service fonctionne bien, on peut le mettre en production.

Au préalable, si le service utilise des images maison, on les pousse sur le registre de production. Pour ce faire, vous devez connecté au registre de production : on s'assure de bien avoir exécuté la commande `docker login registry.picasoft.net`. Les identifiants sont sur le [pass](https://gitlab.utc.fr/picasoft/interne/pass).

```bash
docker-compose push
```

Cette commande pratique indique à Docker Compose de pousser toutes les images du fichier.

On peut aussi le faire manuellement, pour chaque image maison (*i.e.* dont le nom commence par `registry.picasoft.net`) :

```bash
# <image> doit correspondre exactement
# à la directive image du fichier Compose
# et commencer par registry.picasoft.net
docker push <image>
```

Une fois les images poussées, on se rend sur la machine de production et on [lance le service](./launch_service.md).