Bookify the subject

subject/docker-updater/docker-api.md

@@ -1,23 +1,38 @@
 Utiliser l'API de Docker
 ========================
 
-Le Docker Engine expose une API REST sur le protocole HTTP. Comme première
-tentative, vous pouvez essayer de récupérer des informations générales avec un
-simple `curl` :
+Le Docker Engine expose une API REST sur le protocole HTTP. Le client `docker`
+utilise cette API pour communiquer avec le daemon. C'est aussi cette même API
+que `docker-compose` emploie. En fait n'importe quel programme peut en faire
+usage, c'est d'ailleurs très simple d'utilisation.
 
+Si vous n'avez jamais communiqué avec une API REST, voici un premier exemple
+pour récupérer des informations générales sur le daemon Docker avec un simple
+`curl` :
+
+<div lang="en-US">
 ```bash
 curl -s --unix-socket /var/run/docker.sock http://localhost/v1.38/info | jq .
 ```
+</div>
 
-On retrouve un objet JSON contenant des informations similaires à ce que l'on
-obtient avec un `docker info`.
+On utilise l'option `--unix-socket` de `curl` car on ne se connecte pas
+directement à un port, comme c'est le cas habituellement avec le protocole
+HTTP. Bien évidemment lorsque le daemon Docker se trouve sur une machine
+distante (dans le cas de Docker Desktop sur Windows et Mac), on utilise l'IP et
+le port de la machine distance.
+
+Le premier élément dans le chemin de l'URL (`/v1.38/`) correspond à la version
+de l'API que l'on souhaite utiliser. Celle-ci change dès que des
+fonctionnalités sont ajoutées, à l'occasion d'une nouvelle version. Il n'est
+généralement pas nécessaire de mettre à jour cette version dans les programmes
+que vous développez car l'API est rétro-compatible : les anciennes versions de
+l'API restent accessibles.
+
+La commande que l'on a lancé nous retourne un objet JSON contenant des
+informations similaires à ce que l'on obtient avec un `docker info`. L'avantage
+est ici de pouvoir effectuer un traitement programmatique de ces informations.
 
-Le premier élément dans le chemin de l'URL correspond à la version de l'API que
-l'on souhaite utiliser. Celle-ci change dès que des fonctionnalités sont
-ajoutées, à l'occasion d'une nouvelle version. Il n'est généralement pas
-nécessaire de mettre à jour cette version dans les programmes que vous
-développez car l'API est rétro-compatible : les anciennes versions de l'API
-restent accessibles.
 
 Pour réaliser cet exercice, vous pouvez utiliser le langage de votre choix, en
 utilisant des outils ou des bibliothèques cohérents avec l'objectif recherché :

subject/docker-updater/ex-api-updater.md

@@ -5,8 +5,10 @@ Docker) qui pour un conteneur donné :
 
 1. détecte si le conteneur exécute une image disposant d'une mise à jour ;
 1. cherche à récupérer la dernière image disponible ;
-1. mette à jour le contneur ;
-1. dans un conteneur, automatiquement pour toutes les images.
+1. met à jour le conteneur.
+
+Enfin, pour simplifier son utilisation régulière, vous conceverez une image de
+conteneur minimaliste.
 
 ## Étape 1 : Lister les conteneurs
 
@@ -33,7 +35,7 @@ optimistic_meninsky
 
 Écrivez un `Dockerfile` pour conteneuriser ce programme : gérer tant la
 construction (s'il y a des étapes de construction) que l'exécution. En
-utilisant les bonnes pratiques vues en cours.
+utilisant les bonnes pratiques que nous avons pu voir.
 
 ### Exemple d'exécution {-}
 
@@ -104,7 +106,7 @@ suivant si (0) aucune mise à jour de l'image n'est disponible, respectivement
 </div>
 
 N'hésitez pas à utiliser la sortie d'erreur et la sortie standard pour afficher
-des informations pour vous. Celles-ci ne seront pas vérifiées.
+des informations de débogage pour vous.
 
 ::::: {.warning}
 
@@ -112,10 +114,11 @@ des informations pour vous. Celles-ci ne seront pas vérifiées.
 
 Par *image à jour*, on entend : « aligné par rapport à l'image du
 registre ». On ne s'intéresse pas à la date de construction ou de récupération
-de l'image, mais uniquement à son identifiant. Si l'image sur laquelle se base
-un conteneur en cours d'exécution n'a pas le même identifiant que l'image du
-même tag dans le cache d'images, alors on considère que le conteneur doit être
-redémarré (même si la construction ou la récupération est antérieure).\
+de l'image, mais uniquement à son identifiant. En bref : si l'image sur
+laquelle se base un conteneur en cours d'exécution n'a pas le même identifiant
+que l'image du même tag dans le cache d'images, alors on considère que le
+conteneur doit être redémarré (même si la construction ou la récupération est
+antérieure).\
 
 Attention, on souhaite rester sur **le même tag** que celui avec lequel on a
 démarré le conteneur. Il ne s'agit pas de trouver un tag plus récent.
@@ -135,7 +138,7 @@ plus souvent que les autres tags.
 
 ## Étape 3 : Chercher une mise à jour l'image
 
-En ajoutant l'option `--pull`, votre programme va lancer un pull de l'image
+En ajoutant l'option `--pull`, votre programme va lancer un *pull* de l'image
 avant de faire la vérification.
 
 <div lang="en-US">
@@ -154,16 +157,24 @@ avant de faire la vérification.
 ```
 </div>
 
+::::: {.question}
+
 L'image `youp0m` est mise à jour régulièrement. Il y a de forte chance pour
 qu'elle ne soit plus à jour si celle dont vous disposez date de plus d'une
 semaine. Si vous possédez déjà la dernière version de vos conteneurs,
 recherchez une image sur le Docker Hub régulièrement mise à jour pour faire vos
 tests.
 
-Attention une fois l'image *pull* par `ctr-updater`, un appel à nouveau à
-`ctr-updater` sans `--pull` retourne la mise à jour, car le `pull` précédent
+:::::
+
+::::: {.warning}
+
+Une fois l'image *pull* par `ctr-updater`, un nouvel appel à `ctr-updater` sans
+`--pull` indiquera qu'une mise à jour est disponible, car le `pull` précédent
 aura téléchargé localement l'image.
 
+:::::
+
 ::::: {.question}
 
 #### Comment tester lorsqu'on a `pull` toutes ses images ? {-}