diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index ff16431f2af3d03cdc9de30db02d4f8a98133d21..371bc1573078b89c3b0edd66ea122401020b6d8a 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,7 +1,3 @@
-#########################################################################################################################################################
-### WARNING : Manual jobs defined with rules key ARE BLOCKING as long as this issue is unresolved : https://gitlab.com/gitlab-org/gitlab/issues/34077 ###
-#########################################################################################################################################################
-
image: docker:19.03.0
# Disable TLS just for the docker daemon running locally, TLS is still used to deploy built images!
@@ -86,17 +82,16 @@ build:
after_script:
- docker logout $REGISTRY
# Build if Dockerfile changed and previous stage completed successfully
- # Manual build for other changes commented out in order to not block
- # the pipeline (see issue 34077, link on header)
rules:
- changes:
- "pica-*/Dockerfile"
- "meta-*/Dockerfile"
when: on_success
- # - changes:
- # - "pica-*/**"
- # - "meta-*/**"
- # when: manual
+ - changes:
+ - "pica-*/**"
+ - "meta-*/**"
+ when: manual
+ allow_failure: true
- when: never
# Run CoreOS' Clair and make the CI failed if a critical vulnerability isn't in the whitelist
@@ -118,16 +113,15 @@ clair:
rules:
- changes:
- "pica-*/Dockerfile"
- # - "pica-*/docker-compose.yml"
- "pica-*/clair-whitelist.yml"
- "meta-*/Dockerfile"
- # - "meta-*/docker-compose.yml"
- "meta-*/clair-whitelist.yml"
when: on_success
- # - changes:
- # - "pica-*/**"
- # - "meta-*/**"
- # when: manual
+ - changes:
+ - "pica-*/**"
+ - "meta-*/**"
+ when: manual
+ allow_failure: true
- when: never
# Run docker-bench-security and upload the results
@@ -167,6 +161,7 @@ docker-bench-security:
- "pica-*/**"
- "meta-*/**"
when: manual
+ allow_failure: true
- when: never
# Push the generated image on the production registry,
diff --git a/README.md b/README.md
index 40970acbeeb42585f5e9d628254026f5bb8dc3ed..bcf77d0398b240cd622947d3c3883ae1b47c616c 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,7 @@
# Dockerfiles de Picasoft
-**Toute modification du fonctionnement de la chaîne d'intégration (`.gitlab-ci.yml`) doit être documentée dans ce README.**
-
-*Disclaimer* : cette doc est assez longue et peut faire peur ; elle essaye de prévoir tous les cas d'utilisations et d'expliquer à quelqu'un qui débarque. Mais tl;dr : mettez à jour le Dockerfile, poussez sur le dépôt, attendez que tout soit construit et analysé, testez sur l'instance de test, poussez en production, et lancez le service. C'est pas plus compliqué que ça dans la majorité des cas! **Je vous conseille la section [Exemple](#exemple) pour vous donner une idée ! :)**
-
-<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
-
-- [Introduction](#introduction)
-- [Contenu du dépôt](#contenu-du-dpt)
-- [Principes de la CI](#principes-de-la-ci)
- - [Des analyses de sécurité ?](#des-analyses-de-scurit-)
- - [Étapes manuelles ou automatiques ?](#tapes-manuelles-ou-automatiques-)
- - [Meta-images](#meta-images)
-- [Mettre à jour un service existant](#mettre-jour-un-service-existant)
- - [Procédure standard](#procdure-standard)
- - [En cas d'erreur](#en-cas-derreur)
- - [Lors de la construction de l'image](#lors-de-la-construction-de-limage)
- - [Lors de l'analyse de sécurité statique](#lors-de-lanalyse-de-scurit-statique)
- - [Lors de l'analyse de sécurité dynamique](#lors-de-lanalyse-de-scurit-dynamique)
-- [Déployer un service](#dployer-un-service)
-- [Formalisme du dépôt](#formalisme-du-dpt)
-- [Migrer un service à la chaîne d'intégration](#migrer-un-service-la-chane-dintgration)
-- [Troubleshooting](#troubleshooting)
- - [Impossibilité de pull une image](#impossibilit-de-pull-une-image)
- - [Erreurs de connexion à la base de données](#erreurs-de-connexion-la-base-de-donnes)
-- [Astuces](#astuces)
-- [Exemple](#exemple)
-
-<!-- /TOC -->
-
-## Introduction
-
Ce dépôt centralise les Dockerfiles et autre ressources utilisées pour construire **et** déployer les images Docker tournant en production sur l'infrastructure de Picasoft.
-Ce `README` fait office de documentation pour le fonctionnement et le formalisme de ce dépôt, les concepts ainsi que l'historique ne sont pas expliqués en détail. Pour une plongée plus complète dans les différents concepts abordés ici, on pourra se référer aux documentations officielles. Il n'est pas nécessaire de les lire en entier pour travailler sur ce dépôt : ils seront surtout utiles pour comprendre l'existant.
-
-* [Une introduction à Docker : pourquoi et comment](https://docs.docker.com/engine/docker-overview/)
-* [Référence pour l'écriture d'un Dockerfile](https://docs.docker.com/engine/reference/builder/)
-* [Bonnes pratiques pour l'écriture des Dockerfile](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
-* [Orchestrer le lancement de conteneurs avec Docker Compose](https://docs.docker.com/compose/)
-* [Référence pour l'écriture de fichiers Docker Compose](https://docs.docker.com/compose/compose-file/)
-
-Ce dépôt utilise la [chaîne d'intégration de Gitlab](https://docs.gitlab.com/ee/ci/), ou **CI**, pour automatiser certaines tâches dès lors que des changements ont lieu sur le dépôt. L'idée est d'automatiser certaines tâches, ce qui permet d'améliorer la sécurité de l'infrastructure, d'unifier les procédures et de garder un historique clair des modifications.
-
-**À noter : un travail est actuellement en cours pour que l'intégralité des images utilisées en production soient centraliséés sur ce dépôt. Il sera rendu public dès que ce sera le cas.**
-
## Contenu du dépôt
Ce dépôt contient toutes les ressources permettant de déployer les services que nous maintenons sur n'importe quelle machine virtuelle de l'infrastructure de Picasoft, sans prérequis.
@@ -62,281 +19,28 @@ Ainsi, chaque service versionné sur ce dépôt contiendra :
Il n'y a pas de Docker Compose global : chaque service a son propre Docker Compose.
-## Principes de la CI
-
-La CI est déclenchée dès lors qu'une modification est susceptible d'altérer un service, c'est-à -dire dès qu'une modification conforme au [Formalisme du dépôt](#formalisme-du-dpt) est détectée.
-
-Elle va effectuer les opérations suivantes, automatiquement ou manuellement suivant le contexte (voir [Étapes manuelles ou automatiques ?](#tapes-manuelles-ou-automatiques-)) :
-* Initialisation des variables nécessaires pour les autres étapes (dossier, nom et version de l'image modifiée),
-* Construction de l'image Docker et push vers le registre de test,
-* Analyses de sécurité,
-* Push vers le registre de production.
-
-Chaque étape peut échouer et bloquer les étapes ultérieures. Il faudra régler les problèmes et mettre à jour le dépôt afin de relancer la CI le cas échéant.
-
-### Des analyses de sécurité ?
-
-Les analyses de sécurité permettent d'auditer les images Docker que nous construisons, afin de prévenir un maximum de failles de sécurité sur nos services. En effet, bien que les conteneurs Docker soient en théorie isolés du système lui-même, ils contiennent des données critiques. Il faut donc s'assurer que l'image est suffisamment propre avant de la lancer, d'autant qu'on se base parfois sur des images pré-construites.
-
-Les analyses sont de deux types : statique ou dynamique.
-
-L'analyse statique est effectuée par [Clair Scanner](https://github.com/arminc/clair-scanner) : son objectif est d'analyser l'intégralité des paquets installés dans une image Docker et de reporter les vulnérabilités présentes sur ces paquets ([CVE, ou Common Vulnerabilities and Exposures](https://cve.mitre.org/)). Cette analyse ne dit rien sur la sécurité du **service** en lui-même, mais plutôt sur la sécurité des bibliothèques dont il dépend.
-
-L'analyse dynamique est effectuée par [Docker Bench for Security](https://github.com/docker/docker-bench-security), qui lance le service en interne et vérifie que le ou les conteneurs lancés respectent une liste de bonnes pratiques. Docker Bench for Security ne fait jamais échouer la CI, même lorsque les bonnes pratiques ne sont pas respectées, car ce n'est pas toujours possible. Il faut néanmoins tendre vers le respect de ces bonnes pratiques.
-
-### Étapes manuelles ou automatiques ?
-
-Le push sur le registre de production est **toujours** manuel, car il faut s'assurer au préalable que le service a été testé par un humain avant de le pousser.
-
-La mise à jour d'un `Dockerfile` entraîne le lancement de l'ensemble de la CI.
-
-La mise à jour d'une liste blanche de CVE (voir [Formalisme du dépôt](#formalisme-du-dpt)) déclenche uniquement l'analyse de sécurité statique sur la dernière image construite (pas de nécessité de reconstruire l'image).
-
-La mise à jour d'un `docker-compose.yml` déclenche toutes les analyses de sécurité sur la dernière image construite (pas de nécessité de reconstruire l'image).
-
-La mise à jour d'un fichier autre donne la possibilité de déclencher manuellement les étapes de la CI : on appréciera au cas par cas s'il est nécessaire de reconstruire l'image. Par exemple, mettre à jour le `README` ou un fichier de secrets d'exemple ne devrait pas déclencher la CI, tandis que mettre à jour un fichier de configuration devrait déclencher la CI.
-
-### Meta-images
-
-On prévoit à terme d'utiliser ce dépôt pour construire aussi les images qu'il utilise lui même. Pour l'instant, c'est en test avec `meta-registry-test` pour construire l'image utilisée par le registry docker sur `pica01-test`.
-
-## Mettre à jour un service existant
-
-Pour un service qui passe déjà la CI (exemples : Mattermost, Etherpad, Dokuwiki, Backup des BDD...).
-
-Modifier peut vouloir dire :
-* Mettre à jour le service (*e.g.* changer un numéro de version dans le Dockerfile),
-* Mettre à jour la configuration (éditer un fichier quelconque),
-* Mettre à jour la configuration des volumes (*e.g.* changer le point de montage du Docker Compose),
-* etc.
-
-### Procédure standard
-
-Il suffit de récupérer ce dépôt, de faire les mises à jour, de commit les changements et de les pousser.
-
-On n'oublie pas de correctement versionner l'image dans le `docker-compose.yml`, via le tag de l'image.
-Le cas échéant, pour des services "maisons", il est de bon ton de mettre à jour un fichier `CHANGELOG.md` pour résumer les modifications.
-
-*Attention, la CI se déclenche en regardant les modifications apportées lors du dernier commit. Si vous modifiez le `Dockerfile` dans un commit, puis le `README` dans un autre, et que vous poussez le tout, la construction ne se déclenchera pas automatiquement.*
-
-Vous pouvez suivre les différentes étapes de la CI dans la section [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines), et il est **recommandé** de lire les logs des différentes étapes en cliquant sur chacune d'entre elles. Si la construction et les analyses de sécurité se passent bien, tous les voyants sont au vert (sauf la dernière étape, qui doit être déclenchée manuellement). Sinon, référez-vous à la section [En cas d'erreur](#en-cas-derreur).
-
-On peut ensuite [Déployer un service](#dployer-un-service).
-
-### En cas d'erreur
-
-Des erreurs peuvent survenir à plusieurs étapes de la CI.
-Les logs de chaque étape donnent des informations sur la nature de l'erreur.
-
-#### Lors de la construction de l'image
-
-Il est fort probable que l'erreur viennent d'un Dockerfile mal écrit. En général, on testera le Dockerfile en local avant de le pousser sur le dépôt (`docker build`...).
-L'erreur peut aussi venir d'un nom d'image mal formaté dans le Docker Compose (voir [Formalisme du dépôt](#formalisme-du-dpt)).
-
-#### Lors de l'analyse de sécurité statique
-
-Cette analyse échoue lorsque des CVE avec une criticité `High` ou plus sont détectées. Les CVE de niveau plus faible étant inévitables, la CI n'échoue pas et se contente de les afficher.
-
-Clair vous indique quels paquets sont vulnérables. Plusieurs choix s'offrent à vous : mitiger la CVE (choix à privilégier) ou mettre la CVE en liste blanche.
-
-[Mini guide pour mitiger une CVE !](/doc/mini_guide_cve.md)
-
-Une CVE est mise en liste blanche en l'ajoutant au fichier `clair-whitelist.yml`, dont on trouvera un exemple [ici](./pica-mattermost/clair-whitelist.yml). Il faut spécifier le nom de la CVE, le paquet affecté et la raison de la mise en liste blanche.
-
-Une mise en liste blanche est **acceptable** si :
-* Clair détecte des vulnérabilités sur le paquet `linux`. En effet, le noyau utilisé par le conteneur est celui de l'hôte. On utilisera le motif `Vulnérabilité Linux`,
-* Le paquet est à jour et ne peut pas être installé dans une version différente à cause de dépendances d'autres paquets,
-* Le paquet ne peut pas être supprimé,
-* Il n'existe pas de contre-mesure à la vulnérabilité,
-* La vulnérabilité, même si elle est classée en criticité `High`, a peu de conséquences pour Picasoft. Cela peut être le cas pour une attaque par déni de service causant un usage de 100% du processeur, qui n'aura d'impact que sur Etherpad en raison des limitations de ressources.
-
-Ensuite, on pousse les modifications et la CI ré-effectuera les tests de vulnérabilités, en reconstruisant l'image si nécessaire.
-
-#### Lors de l'analyse de sécurité dynamique
-
-Il est fort probable que l'erreur provienne d'un mauvais Docker Compose, et que Docker Bench for Security n'arrive pas à lancer votre ou vos conteneur(s), par exemple à cause d'un fichier manquant ou d'un mauvais formattage.
-
-## Déployer un service
-
-Une fois les premières étapes de la CI passées, il est temps de déployer le service.
-
-À ce stade, l'image est construite, saine, et poussée sur le registre de test. Avant de la mettre en production, il faut vérifier que le service se lance bien comme prévu. Pour ce faire, on se rend sur une machine virtuelle de test (exemple : `pica01-test.picasoft.net`) et on se rend dans `/DATA/docker/dockerfiles`.
-
-Il faut être connecté au registre de test pour la suite : on s'assure de bien avoir exécuté la commande `docker login registry.test.picasoft.net`. Les identifiants sont sur le [pass](https://gitlab.utc.fr/picasoft/interne/pass).
-
-Pour que le service réponde à nos critères, il faut s'assurer qu'il démarre **indépendamment** de ce qui existe sur la machine. Le script [`docker_test.sh`](./docker_test.sh) s'occupe de tout cela pour vous.
-Il suffit de lancer la commande `$ ./docker_test.sh <nom du dossier, e.g. pica-mattermost>` pour effectuer les opérations suivantes :
-* Mise à jour du dépôt dans sa dernière version,
-* Remplacement des URL en `picasoft.net` par `test.picasoft.net`,
-* Création d'un fichier de secrets avec les valeurs d'exemple du dépôt,
-* Remise à zéro des volumes Docker existants,
-* Suppression des anciennes images,
-* Pull de la nouvelle version de(s) l'image(s),
-* Lancement de Docker Compose,
-* Affichage des logs.
-
-Vérifiez que les logs ne produisent aucune erreur et que le service fonctionne bien sur l'infrastructure de test.
-
-Lorsque tout est bon, on retourne sur la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines), et on lance le push de l'image sur le registre de production.
-
-On se rend enfin sur la machine de production, dans le dossier `/DATA/docker/dockerfiles`. On s'assure que les fichiers de secrets existent et contiennent bien des valeurs **secrètes**, pas celles du fichier d'exemple !
-
-Il faut être connecté au registre de production pour la suite : 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).
-
- On peut alors utiliser le script [`docker_prod.sh`](./docker_prod.sh), qui automatise quelques étapes.
- Il suffit de lancer la commande `$ ./docker_prod.sh <nom du dossier>` pour effectuer les opérations suivantes :
-* Mise à jour du dépôt dans sa dernière version,
-* Création des volumes Docker non-existants,
-* Pull de la nouvelle version de(s) l'image(s),
-* Lancement de Docker Compose,
-* Affichage des logs.
-
-Attention : un conteneur noté `Unhealthy` à cause d'un mauvais `HEALTHCHECK` sera **exclu** de Traefik, même s'il fonctionne bien!
-
-## Formalisme du dépôt
-
-Pour que la CI et le déploiement des services fonctionnent correctement, il faut respecter plusieurs contraintes sur la nomenclature, l'arborescence et le contenu des fichiers. Il ne s'agit pas ici de bonnes pratiques - voir le rapport Docker Bench for Security pour cela.
-
-* Chaque service géré par la chaîne d'intégration est dans un sous-dossier `pica-*` ou `meta-*`,
-* Chaque sous-dossier contient au moins un `Dockerfile`, un `docker-compose.yml` et un `clair-whitelist.yml`,
-* Le nom final de l'image est spécifiée dans le `docker-compose.yml`, au format `registry.picasoft.net/<nom image>:<version image>`, et doit être **la même que le nom du dossier**,
-* Les secrets sont répertoriés dans des fichiers `<nom>.secrets.example` dans un sous-dossier `secrets`, avec des valeurs d'exemple,
-* Le dossier `secrets` doit avoir comme permissions `770` et les fichiers à l'intérieur de ce dossier `660`. Tous les dossiers et fichiers de ce dépôt doivent avoir pour groupe `docker` (gid: `999`),
-* Les fichiers de secrets sont injectés dans le conteneur via la directive `env_file`, sans l'extension `.example`,
-* Tous les volumes du Docker Compose sont déclarés comme `external` (pour éviter leur suppression lors d'un `docker-compose down`, ce qui serait dramatique),
-* Le Docker Compose déclare un réseau Docker externe nommé `docker_default`, pour pouvoir rejoindre le réseau de Traefik.
-
-Un exemple concret peut être trouvé au niveau de [pica-mattermost](./pica-mattermost) ou [pica-etherpad](./pica-etherpad). Un dossier [template](./template) prêt à copier est aussi disponible.
-
-## Migrer un service à la chaîne d'intégration
-
-Tous les services répertoriés sur ce dépôt ne passent pas encore la chaîne d'intégration. Pour les migrer dessus, il suffit de modifier les sous-dossiers des services pour qu'ils respectent le [Formalisme du dépôt](#formalisme-du-dpt).
-
-Ensuite, il faudra les supprimer du `docker-compose.yml` global présent dans `/DATA/docker` sur les machines, et les déployer en utilisant les Docker Compose individuels.
-
-## Troubleshooting
-
-Cette section répertorie les problèmes anecdotiques indépendants des modifications des fichiers.
-
-### Impossibilité de pull une image
-
-Parfois, un timeout empêche de pull l'image depuis le registre de test entre deux étapes, avec des messages de timeout ou de type `Unknown blob`. Il faudra dans ce cas redémarrer le registre de test (sur `pica01-test`, probablement) et relancer la chaîne d'intégration.
-
-### Erreurs de connexion à la base de données
-
-Si le conteneur `*-app` n'arrive pas à se connecter à la BDD du conteneur `*-db`, il est possible que `*-db` soit en train de tourner avec des anciens identifiants. Pour corriger ce problème **sur la VM de test**, il faudra:
-
-* effacer les conteneurs `*-app` et `*-db`
-* effacer leurs volumes
-* créer à nouveau leurs volumes
-* relancer le script `./docker_test.sh`.
-
-**Note:** Le script s'occupe déjà d'effacer et créer à nouveau les volumes, mais ça ne fonctionne pas dans le cas de `pica-etherpad`, probablement dû à un bug de `docker-compose config --volumes` qui retourne `etherpad-db-volume` et non `etherpad-db`.
-
-## Astuces
-
-Si pour une quelconque raison, on souhaite pousser un commit sans déclencher la chaîne d'intégration, on pourra ajouter `[skip ci]` au message du commit.
-
-Il est aussi possible de relancer une pipeline plus ancienne, pour reconstruire une ancienne version de l'image, quand cela est nécessaire, et revenir exactement dans l'état indiqué par le dépôt.
-
-## Exemple
-
-On veut mettre à jour Mattermost de la version 5.18.0 à la version 5.19.0. On fait les modifications dans le Dockerfile et on pousse le commit. Les modifications dépendent évidemment du service, on peut voir le commit [472e0d72](https://gitlab.utc.fr/picasoft/projets/dockerfiles/commit/472e0d72534659e215270adade6746b65b6f65e3) pour l'exemple.
-
-Le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) se lance automatiquement. Je suis les logs des jobs un par un pour vérifier que tout se passe bien.
-
-La construction de l'image et les analyses de vulnérabilité se passent bien : aucun paquet n'introduit de nouvelle vulnérabilité.
-
-Je me rends sur `pica01-test` et je teste la nouvelle version de l'image :
-
-```bash
-$ ssh qduchemi@pica01-test.picasoft.net
-qduchemi@pica01-test:~$ cd /DATA/docker/dockerfiles
-qduchemi@pica01-test:/DATA/docker/dockerfiles$ ./docker_test.sh pica-mattermost
-Starting procedure for pica-mattermost/...
-
-==== Create dumb secret files ====
- File pica-mattermost//secrets/mattermost-db.secrets created
-
-==== Stop and remove existing containers ====
-Network docker_default is external, skipping
-
-==== RESET HARD and pull Dockerfiles repository ====
-Using branch master, is this correct ? [y/N]
-y
-HEAD is now at 472e0d7 [Mattermost] Bump to version 5.19.0
-Username for 'https://gitlab.utc.fr': qduchemi
-Password for 'https://qduchemi@gitlab.utc.fr':
-Already up-to-date.
-
-==== Replace production URL with testing URL in all files ====
- Found in ./entrypoint.sh
- Found in ./docker-compose.yml
-
-==== Remove and re-create named external volumes ====
-mattermost-config
-mattermost-config
-mattermost-data
-mattermost-data
-mattermost-plugins
-mattermost-plugins
-mattermost-db
-mattermost-db
-
-==== Remove old images ====
-Error: No such image: registry.test.picasoft.net/pica-mattermost:5.19.0
-Error: No such image: postgres:9.4-alpine
-
-==== Pull new versions of images ====
-Pulling mattermost-db ... done
-Pulling mattermost ... done
+Un exemple concret peut être trouvé au niveau de [pica-mattermost](./pica-mattermost) ou [pica-etherpad](./pica-etherpad).
-==== Lauch pica-mattermost/ and restore repository ====
-Creating mattermost-db ... done
-Creating mattermost-app ... done
-HEAD is now at 472e0d7 [Mattermost] Bump to version 5.19.0
+## Mais je commence par où, bordel ?
-==== Print logs (use Ctrl+C to stop) ====
-Attaching to mattermost-app, mattermost-db
-[...]
-```
+On peut vite se perdre sur ce dépôt, en fonction de ce que l'on veut faire.
-Je vérifie que les logs sont ok, je se rend sur [team.test.picasoft.net](https://team.test.picasoft.net) et je constate que tout fonctionne.
+### Je veux lancer un service existant sur une machine virtuelle
-Je me rends de nouveau sur le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) et je lance manuellement l'étape `push-prod` pour pousser l'image sur le registre de production.
+Si le service que vous souhaitez lancer est référencé sur ce dépôt, la documentation pour le tester et le déployer se trouve [ici](./doc/guide_deploiement.md).
-Je me rends ensuite sur la machine de production (`pica02` Ã ce jour) et je lance la nouvelle version du service :
-```bash
-$ ssh qduchemi@pica02.picasoft.net
-qduchemi@pica02:~$ cd /DATA/docker/dockerfiles
-qduchemi@pica02:/DATA/docker/dockerfiles$ ./docker_prod.sh pica-mattermost
-Starting procedure for pica-mattermost...
+### Je veux mettre à jour un service
-==== Pull Dockerfiles repository ====
-Using branch master, is this correct ? [y/N]
-y
-Username for 'https://gitlab.utc.fr': qduchemi
-Password for 'https://qduchemi@gitlab.utc.fr':
-Déjà à jour.
+Il faut pour cela utiliser la chaîne d'intégration de ce dépôt, qui construit automatiquement les images Docker. La documentation utilisateur se trouve [ici](./doc/guide_utilisateur_ci.md)
-==== Pull new versions of images ====
-Pulling mattermost-db ... done
-Pulling mattermost ... done
+### Je veux mettre en place un nouveau service
-==== Ensure named external volumes are created ====
-mattermost-config
-mattermost-data
-mattermost-plugins
-mattermost-db
+Il faudra d'une part respecter les conventions utilisées par la chaîne d'intégration, qui sont disponibles [ici](./doc/guide_utilisateur_ci.md#formalisme-du-dpt).
-==== Lauch pica-mattermost ====
-Recreating mattermost-db ... done
-Recreating mattermost-app ... done
+Ensuite, il faudra jeter un oeil [aux bonnes pratiques](./doc/guide_bonnes_pratiques.md) Ã l'oeuvre sur l'infrastructure de Picasoft.
-==== Print logs (use Ctrl+C to stop) ====
-Attaching to mattermost-app, mattermost-db
-```
+Un dossier [template](./template) prêt à copier est aussi disponible.
-J'attends que l'application ait démarré, je vérifie que tout est ok sur [team.picasoft.net](https://team.picasoft.net).
+### Je veux améliorer la chaîne d'intégration
-La mise à jour est terminée ! :)
+Il existe une documentation "développeur" pour la chaîne d'intégration, qui rentre plus en détail, disponible [ici](./doc/guide_developpeur_ci.md).
diff --git a/doc/guide_bonnes_pratiques.md b/doc/guide_bonnes_pratiques.md
new file mode 100644
index 0000000000000000000000000000000000000000..af1eae10e654b6db36c63212a855fa43562dd34f
--- /dev/null
+++ b/doc/guide_bonnes_pratiques.md
@@ -0,0 +1,120 @@
+## Introduction
+
+Ce mini-guide vous donne des pistes pour créer de nouveaux services, tout en restant harmonieux par rapport à l'infrastructure existante.
+
+Pour une plongée plus complète dans les différents concepts abordés ici, on pourra se référer aux documentations officielles. Il n'est pas nécessaire de les lire en entier pour travailler sur ce dépôt : ils seront surtout utiles pour comprendre l'existant.
+
+* [Une introduction à Docker : pourquoi et comment](https://docs.docker.com/engine/docker-overview/)
+* [Référence pour l'écriture d'un Dockerfile](https://docs.docker.com/engine/reference/builder/)
+* [Bonnes pratiques pour l'écriture des Dockerfile](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+* [Orchestrer le lancement de conteneurs avec Docker Compose](https://docs.docker.com/compose/)
+* [Référence pour l'écriture de fichiers Docker Compose](https://docs.docker.com/compose/compose-file/)
+
+## Dockerfile
+
+Une [série de recommendations](https://wiki.picasoft.net/doku.php?id=technique:docker:tips) est disponible ici pour l'écriture des Dockerfile.
+
+## Volumes
+
+Une fois que l'on a identifié les dossiers du conteneur où l'on a besoin de persistence, il y a plusieurs manières de procéder :
+* Soit utiliser un dossier de l'hôte comme stockage, via un [bind mount](https://docs.docker.com/storage/bind-mounts/)
+* Soit utiliser un [volume Docker](https://docs.docker.com/storage/volumes/), géré en interne par Docker.
+
+Chacun a ses avantages et inconvénients, voilà ce que l'on fait chez Picasoft :
+* Pour **monter un ou des fichiers existants** dans un conteneur, on utilise un bind mount,
+* Pour **assurer la persistence d'un dossier du conteneur**, on utilise un volume Docker.
+
+### Bind mounts
+
+Si le fichier à monter est versionné sur ce dépôt, on utilisera un chemin relatif. Sinon, on utilisera des chemins absolus, ce qui enlève du côté "indépendant des machines", mais parfois on ne peut pas faire autrement. Par exemple, quand des certificats sont stockés sur une machine de production dans un dossier spécifique, on est obligés d'y faire référence.
+
+Exemple :
+
+```yaml
+services:
+ volumes:
+ # Dossier contenant les certificats sur les machines de production : utilisation du chemin absolu
+ - /DATA/docker/certs/example.picasoft.net:/certs
+ # Fichier de configuration versionné dans le même dossier : utilisation du chemin relatif
+ - ./config.json:/etc/config.json
+```
+
+### Volumes Docker
+
+Si on veut indiquer qu'un des dossiers du conteneur doit persister au fil des recréations, alors on utilise des volumes Docker. C'est typiquement le cas pour le dossier `/var/lib/postgresql/data` d'une base Postgres, qui ne doit pas supprimer les données à chaque recréation du conteneur.
+
+Exemple à reprendre :
+
+```yaml
+volumes:
+ # Nom utilisé dans le fichier docker-compose.yml
+ db:
+ # Vrai nom du volume Docker
+ name: etherpad_db
+ # On préfère gérer les volumes nous-même
+ external: true
+
+ services:
+ exemple:
+ volumes:
+ # On fait référence au "db" défini ci-dessus, et on le monte sur /mount_point
+ - db:/mount_point
+```
+
+## Reverse-proxy
+
+Si le service est un service **HTTP(S)** (*i.e.* Web), on utilisera systématiquement le reverse-proxy [Traefik](https://wiki.picasoft.net/doku.php?id=technique:infrastructure:archi#traefik) et on bindera **pas** son port interne sur un port de l'hôte.
+
+En effet, Traefik permet de gérer tout pour nous : la redirection vers le bon conteneur et le bon port en fonction du nom de domaine, la création et le renouvellement des certificats, etc.
+
+Il suffit pour ce faire d'ajouter les bons labels, et d'ajouter le conteneur au réseau par défaut de Traefik, qui s'appelle `docker_default`, et existe indépendamment de Docker Compose.
+
+Exemple à reprendre :
+
+```yaml
+networks:
+ docker_default:
+ external: true
+
+services:
+ exemple:
+ networks:
+ - docker_default
+```
+
+## Réseaux
+
+L'idée est de mettre dans des réseaux séparés les services n'ayant pas besoin de communiquer entre eux, pour améliorer la sécurité de l'infrastructure.
+
+Imaginons un service web et sa base de données. Le service web a besoin d'être exposé sur Internet, via Traefik, mais sa base de données n'a pas besoin ! D'autant que si on a la rajoutait au réseau `docker_default`, elle serait également accessible des autres conteneurs du réseau.
+
+Ce qui nous donnerait quelque chose comme :
+
+```yaml
+networks:
+ docker_default:
+ external: true
+ db:
+
+services:
+ exemple:
+ # On voit que le service est dans le réseau docker_default, pour être
+ # accessible depuis Traefik, mais aussi dans le réseau db, pour
+ # pouvoir parler à la base de données.
+ networks:
+ - docker_default
+ - db
+ exemple_db:
+ networks:
+ - db
+```
+
+## Mise en place de TLS
+
+Si le service est un service **TLS**, mais n'est pas un service web, alors il a besoin de certificats. Ces certificats peuvent être générés par Traefik en lui "faisant croire" que c'est un service web, mais on ne peut pas passer par lui pour servir les requêtes. C'est le cas pour le LDAP, le serveur mail... on utilisera dans ce cas l'outil [TLS Certs Monitor](./pica-tls-certs-monitor). En pratique, cela revient à ajouter des labels dans le Docker Compose du dépôt.
+
+Si plusieurs conteneurs doivent partager un même volume, on accordera les noms dans les fichiers Docker Compose du dépôt.
+
+## Divers
+
+On préférera utiliser la politique `restart: unless-stopped` pour les services. Ceci évite qu'un service arrêté explicitement ne se relance tout seul au démarrage de la machine.
diff --git a/doc/guide_deploiement.md b/doc/guide_deploiement.md
new file mode 100644
index 0000000000000000000000000000000000000000..8795626299e6b0faebcb711030c7cb041b516ae5
--- /dev/null
+++ b/doc/guide_deploiement.md
@@ -0,0 +1,140 @@
+# Déployer un service
+
+Dès lors que la chaîne d'intégration a construit une image Docker, il est possible de tester et de déployer le service concerné.
+
+## Test du service
+
+Avant de mettre un service en production, il faut vérifier que le service se lance bien comme prévu. Pour ce faire, on se rend sur une machine virtuelle de test (exemple : `pica01-test.picasoft.net`) et on se rend dans `/DATA/docker/dockerfiles`.
+
+Il faut être connecté au registre de test pour la suite : on s'assure de bien avoir exécuté la commande `docker login registry.test.picasoft.net`. Les identifiants sont sur le [pass](https://gitlab.utc.fr/picasoft/interne/pass).
+
+Pour que le service réponde à nos critères, il faut s'assurer qu'il démarre **indépendamment** de ce qui existe sur la machine. Le script [`docker_test.sh`](./docker_test.sh) s'occupe de tout cela pour vous.
+Il suffit de lancer la commande `$ ./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.
+
+## Déploiement en production
+
+Lorsque le test a fonctionné, on se rend sur la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines) on choisit la pipeline correspondant au commit de modification que l'on a testé, et on lance le push de l'image sur le registre de production (`push-prod`).
+
+On se rend enfin sur la machine de production, dans le dossier `/DATA/docker/dockerfiles`.
+
+Si on déploie un service pour la première fois, il faudra copier les fichiers `*.secrets.example` en `*.secrets`, et remplacer les valeurs d'example par des valeurs **secrètes**.
+
+Il faut être connecté au registre de production pour la suite : 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).
+
+ On peut alors utiliser le script [`docker_prod.sh`](./docker_prod.sh), qui automatise quelques étapes.
+ Il suffit de lancer la commande `$ ./docker_prod.sh <nom du dossier>`.
+
+Attention : un conteneur noté `Unhealthy` à cause d'un mauvais `HEALTHCHECK` sera **exclu** de Traefik, même s'il fonctionne bien!
+
+## Exemple de déploiement
+
+Je me rends sur `pica01-test` et je teste la nouvelle version de l'image :
+
+```bash
+$ ssh qduchemi@pica01-test.picasoft.net
+qduchemi@pica01-test:~$ cd /DATA/docker/dockerfiles
+qduchemi@pica01-test:/DATA/docker/dockerfiles$ ./docker_test.sh pica-mattermost
+Starting procedure for pica-mattermost/...
+
+==== Create dumb secret files ====
+ File pica-mattermost//secrets/mattermost-db.secrets created
+
+==== Stop and remove existing containers ====
+Network docker_default is external, skipping
+
+==== RESET HARD and pull Dockerfiles repository ====
+Using branch master, is this correct ? [y/N]
+y
+HEAD is now at 472e0d7 [Mattermost] Bump to version 5.19.0
+Username for 'https://gitlab.utc.fr': qduchemi
+Password for 'https://qduchemi@gitlab.utc.fr':
+Already up-to-date.
+
+==== Replace production URL with testing URL in all files ====
+ Found in ./entrypoint.sh
+ Found in ./docker-compose.yml
+
+==== Remove and re-create named external volumes ====
+mattermost-config
+mattermost-config
+mattermost-data
+mattermost-data
+mattermost-plugins
+mattermost-plugins
+mattermost-db
+mattermost-db
+
+==== Remove old images ====
+Error: No such image: registry.test.picasoft.net/pica-mattermost:5.19.0
+Error: No such image: postgres:9.4-alpine
+
+==== Pull new versions of images ====
+Pulling mattermost-db ... done
+Pulling mattermost ... done
+
+==== Lauch pica-mattermost/ and restore repository ====
+Creating mattermost-db ... done
+Creating mattermost-app ... done
+HEAD is now at 472e0d7 [Mattermost] Bump to version 5.19.0
+
+==== Print logs (use Ctrl+C to stop) ====
+Attaching to mattermost-app, mattermost-db
+[...]
+```
+
+Je vérifie que les logs sont ok, je se rend sur [team.test.picasoft.net](https://team.test.picasoft.net) et je constate que tout fonctionne.
+
+Je me rends de nouveau sur le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) et je lance manuellement l'étape `push-prod` pour pousser l'image sur le registre de production.
+
+Je me rends ensuite sur la machine de production (`pica02` Ã ce jour) et je lance la nouvelle version du service :
+```bash
+$ ssh qduchemi@pica02.picasoft.net
+qduchemi@pica02:~$ cd /DATA/docker/dockerfiles
+qduchemi@pica02:/DATA/docker/dockerfiles$ ./docker_prod.sh pica-mattermost
+Starting procedure for pica-mattermost...
+
+==== Pull Dockerfiles repository ====
+Using branch master, is this correct ? [y/N]
+y
+Username for 'https://gitlab.utc.fr': qduchemi
+Password for 'https://qduchemi@gitlab.utc.fr':
+Déjà à jour.
+
+==== Pull new versions of images ====
+Pulling mattermost-db ... done
+Pulling mattermost ... done
+
+==== Ensure named external volumes are created ====
+mattermost-config
+mattermost-data
+mattermost-plugins
+mattermost-db
+
+==== Lauch pica-mattermost ====
+Recreating mattermost-db ... done
+Recreating mattermost-app ... done
+
+==== Print logs (use Ctrl+C to stop) ====
+Attaching to mattermost-app, mattermost-db
+```
+
+J'attends que l'application ait démarré, je vérifie que tout est ok sur [team.picasoft.net](https://team.picasoft.net).
+
+La mise à jour est terminée ! :)
+
+## Troubleshooting
+
+Cette section répertorie les problèmes anecdotiques indépendants des modifications des fichiers.
+
+### Erreurs de connexion à la base de données
+
+Si le conteneur `*-app` n'arrive pas à se connecter à la BDD du conteneur `*-db`, il est possible que `*-db` soit en train de tourner avec des anciens identifiants. Pour corriger ce problème **sur la VM de test**, il faudra:
+
+* effacer les conteneurs `*-app` et `*-db`
+* effacer leurs volumes
+* créer à nouveau leurs volumes
+* relancer le script `./docker_test.sh`.
+
+**Note:** Le script s'occupe déjà d'effacer et créer à nouveau les volumes, mais ça ne fonctionne pas dans le cas de `pica-etherpad`, probablement dû à un bug de `docker-compose config --volumes` qui retourne `etherpad-db-volume` et non `etherpad-db`.
diff --git a/doc/guide_developpeur_ci.md b/doc/guide_developpeur_ci.md
new file mode 100644
index 0000000000000000000000000000000000000000..e4fe00ab8037acf9257fca3e75e1e53d71cbc122
--- /dev/null
+++ b/doc/guide_developpeur_ci.md
@@ -0,0 +1,46 @@
+# Explications et améliorations de la CI
+
+Cette section répertorie des détails un peu plus poussés sur le fonctionnement de la chaîne d'intégration, qui viendraient parasiter le guide de fonctionnement normal.
+
+Tout est configuré dans le fichier [.gitlab-ci.yml](../.gitlab-ci.yml). Sa lecture est sans doute un peu cryptique pour certaines parties, on pourra consulter la documentation de Gitlab pour l'explication des différentes directives.
+
+## Formalisme du dépôt
+
+Pour que la CI fonctionne correctement, il faut respecter plusieurs contraintes. Il ne s'agit pas de bonnes pratiques, mais de conventions (discutables).
+
+On peut utiliser le [template fourni](../template) pour partir sur une bonne base.
+
+* Chaque service géré par la chaîne d'intégration a son dossier `pica-*` ou `meta-*`,
+* Chaque dossier contient au moins un `Dockerfile`, un `docker-compose.yml` et un `clair-whitelist.yml`,
+* Le nom final de l'image est spécifiée dans le `docker-compose.yml`, au format `registry.picasoft.net/nom:version`, et le nom doit correspondre au dossier,
+* Les secrets sont répertoriés dans des fichiers `*.secrets.example` dans un sous-dossier `secrets`, avec des valeurs d'exemple,
+* Le dossier `secrets` doit avoir comme permissions `770` et les fichiers à l'intérieur de ce dossier `660`. Tous les dossiers et fichiers de ce dépôt doivent avoir pour groupe `docker` (gid: `999`),
+* Les fichiers de secrets sont injectés dans le conteneur via la directive `env_file`, sans l'extension `.example`.
+
+## Des analyses de sécurité ?
+
+Les analyses de sécurité permettent d'auditer les images Docker que nous construisons, afin de prévenir un maximum de failles de sécurité sur nos services. En effet, bien que les conteneurs Docker soient en théorie isolés du système lui-même, ils contiennent des données critiques. Il faut donc s'assurer que l'image est suffisamment propre avant de la lancer, d'autant qu'on se base parfois sur des images pré-construites.
+
+Les analyses sont de deux types : statique ou dynamique.
+
+L'analyse statique est effectuée par [Clair Scanner](https://github.com/arminc/clair-scanner) : son objectif est d'analyser l'intégralité des paquets installés dans une image Docker et de reporter les vulnérabilités présentes sur ces paquets ([CVE, ou Common Vulnerabilities and Exposures](https://cve.mitre.org/)). Cette analyse ne dit rien sur la sécurité du **service** en lui-même, mais plutôt sur la sécurité des bibliothèques dont il dépend.
+
+Cette analyse n'échoue que lorsque des CVE de niveau `High` ou plus sont détectées. Le fichier `clair-whitelist.yml` sert justement à autoriser certaines CVE de niveau `High` à contourner cette restriction, après une analyse qui aurait déterminé qu'elle n'affecte pas la sécurité de notre service.
+
+L'analyse dynamique est effectuée par [Docker Bench for Security](https://github.com/docker/docker-bench-security), qui lance le service en interne et vérifie que le ou les conteneurs lancés respectent une liste de bonnes pratiques. Docker Bench for Security ne fait jamais échouer la CI, même lorsque les bonnes pratiques ne sont pas respectées, car ce n'est pas toujours possible. Il faut néanmoins tendre vers le respect de ces bonnes pratiques. En pratique, nous utilisons très peu cette étape et sa pertinence devra être discutée.
+
+## Étapes manuelles ou automatiques ?
+
+Le push sur le registre de production est **toujours** manuel, car il faut s'assurer au préalable que le service a été testé par un humain avant de le pousser.
+
+La mise à jour d'un `Dockerfile` entraîne le lancement de l'ensemble de la CI.
+
+La mise à jour d'une liste blanche de CVE (voir [Formalisme du dépôt](#formalisme-du-dpt)) déclenche uniquement l'analyse de sécurité statique sur la dernière image construite (pas de nécessité de reconstruire l'image).
+
+La mise à jour d'un `docker-compose.yml` déclenche l'analyse de sécurité dynamique sur la dernière image construite (pas de nécessité de reconstruire l'image).
+
+La mise à jour d'un fichier autre donne la possibilité de déclencher manuellement les étapes de la CI : on appréciera au cas par cas s'il est nécessaire de reconstruire l'image. Par exemple, mettre à jour le `README` ou un fichier de secrets d'exemple ne devrait pas déclencher la CI, tandis que mettre à jour un fichier de configuration devrait déclencher la CI.
+
+## Meta-images
+
+On prévoit à terme d'utiliser ce dépôt pour construire aussi les images qu'il utilise lui même. Pour l'instant, c'est en test avec `meta-registry-test` pour construire l'image utilisée par le registry docker sur `pica01-test`.
diff --git a/doc/guide_utilisateur_ci.md b/doc/guide_utilisateur_ci.md
new file mode 100644
index 0000000000000000000000000000000000000000..35669699c266494c2740fbc811f55ddf3ec0ccc4
--- /dev/null
+++ b/doc/guide_utilisateur_ci.md
@@ -0,0 +1,78 @@
+# Utilisation de la chaîne d'intégration
+
+## Introduction
+
+Ce dépôt utilise la [chaîne d'intégration de Gitlab](https://docs.gitlab.com/ee/ci/), ou **CI**, pour automatiser certaines tâches dès lors que des changements ont lieu sur le dépôt. L'idée est en particulier d'automatiser la construction des images Docker et les analyses de sécurité, ce qui permet d'améliorer la sécurité de l'infrastructure, d'unifier les procédures, de garder un historique clair des modifications et de synchroniser l'état des services sur les machines avec l'état de ce dépôt.
+
+La CI est déclenchée dès lors qu'une modification est susceptible d'altérer un service est détectée.
+
+Elle va effectuer les opérations suivantes, partiellement ou complètement selon le contexte :
+* Détection de l'image modifiée,
+* Construction de l'image Docker et push vers le registre de test,
+* Analyses de sécurité,
+* Push vers le registre de production.
+
+Chaque étape peut échouer et bloquer les étapes ultérieures. Il faudra régler les problèmes et mettre à jour le dépôt afin de relancer la CI le cas échéant.
+
+## Mettre à jour un service
+
+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.
+
+En principe, il suffit de récupérer ce dépôt, de faire les mises à jour souhaitées, de commit les changements et de les pousser pour que l'image soit construite si besoin. Le cas échéant, pour des services "maisons", il est de bon ton de mettre à jour un fichier `CHANGELOG.md` pour résumer les modifications.
+
+Si vous mettez à jour un fichier de configuration qui nécessite de reconstruire l'image, il faudra lancer la CI manuellement depuis la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines). Si vous mettez à jour un fichier de configuration qui est monté dans le conteneur via Docker Compose, aucune action de la CI n'est nécessaire, **même pas l'action `push-prod`**.
+
+Notez que le **nom final** de l'image construite est celui que vous indiquez dans le `docker-compose.yml`. Si vous mettez à jour un service en lui-même (option 1 de la liste ci-dessus), il faut impérativement modifier la version de l'image construite dans ce fichier dans le `docker-compose.yml`.
+
+**Attention, la CI se déclenche en regardant les modifications apportées lors du dernier commit. Si vous modifiez le `Dockerfile` dans un commit, puis le `README` dans un autre, et que vous poussez le tout, la construction ne se déclenchera pas automatiquement.**
+
+Vous pouvez suivre les différentes étapes de la CI sur la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines), et il est **recommandé** de lire les logs des différentes étapes en cliquant sur chacune d'entre elles. Si la construction et les analyses de sécurité se passent bien, tous les voyants sont au vert (sauf la dernière étape, qui doit être déclenchée manuellement). Sinon, référez-vous à la section [Troubleshooting](#troubleshooting).
+
+On peut ensuite [déployer le service](guide_deploiement.md).
+
+## Exemple de mise à jour
+
+On veut mettre à jour Mattermost de la version 5.18.0 à la version 5.19.0. On fait les modifications dans le Dockerfile et on pousse le commit. Les modifications dépendent évidemment du service, on peut voir le commit [472e0d72](https://gitlab.utc.fr/picasoft/projets/dockerfiles/commit/472e0d72534659e215270adade6746b65b6f65e3) pour l'exemple.
+
+Le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) se lance automatiquement. Je suis les logs des jobs un par un pour vérifier que tout se passe bien.
+
+La construction de l'image et les analyses de vulnérabilité se passent bien : aucun paquet n'introduit de nouvelle vulnérabilité.
+
+Je [déploie la nouvelle version du service](./guide_deploiement.md).
+
+Si tout se passe bien, je me rends de nouveau sur le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) et je lance manuellement l'étape `push-prod` pour pousser l'image sur le registre de production.
+
+## Astuces
+
+Il est possible de relancer une pipeline plus ancienne, pour reconstruire une ancienne version de l'image, quand cela est nécessaire, et revenir exactement dans l'état du commit concerné.
+
+## Troubleshooting
+
+Des erreurs peuvent survenir à plusieurs étapes de la CI.
+Les logs de chaque étape donnent des informations sur la nature de l'erreur.
+
+### Impossibilité de pull une image
+
+Parfois, un timeout empêche de pull l'image depuis le registre de test entre deux étapes, avec des messages de timeout ou de type `Unknown blob`. Il faudra dans ce cas redémarrer le registre de test (sur `pica01-test`, probablement) et relancer la chaîne d'intégration.
+
+### Lors de la construction de l'image
+
+Si l'erreur ne vient pas d'un Dockerfile mal écrit, elle peut venir d'un nom d'image mal formaté dans le Docker Compose (voir [Formalisme du dépôt](./guide_developpeur_ci#formalisme-du-dpt)).
+
+### Lors de l'analyse de sécurité statique
+
+Cette analyse échoue lorsque des CVE avec une criticité `High` ou plus sont détectées. Les CVE de niveau plus faible étant inévitables, la CI n'échoue pas et se contente de les afficher.
+
+Clair vous indique quels paquets sont vulnérables. Plusieurs choix s'offrent à vous : mitiger la CVE (choix à privilégier) ou mettre la CVE en liste blanche.
+
+On regardera à ce titre le [Mini guide pour mitiger une CVE !](mini_guide_cve.md)
+
+Ensuite, on pousse les modifications et la CI ré-effectuera les tests de vulnérabilités, en reconstruisant l'image si nécessaire.
+
+### Lors de l'analyse de sécurité dynamique
+
+Il est fort probable que l'erreur provienne d'un mauvais Docker Compose, et que Docker Bench for Security n'arrive pas à lancer votre ou vos conteneur(s), par exemple à cause d'un fichier manquant ou d'un mauvais formattage.
diff --git a/doc/mini_guide_cve.md b/doc/mini_guide_cve.md
index f905a8f18cd8a199d82a52c32143177e6c57a393..050b0e593789383c7956b0005bed195ed9985a68 100644
--- a/doc/mini_guide_cve.md
+++ b/doc/mini_guide_cve.md
@@ -1,5 +1,14 @@
# Mini guide pour mitiger une CVE (WIP)
+Une CVE est mise en liste blanche en l'ajoutant au fichier `clair-whitelist.yml`, dont on trouvera un exemple [ici](../pica-mattermost/clair-whitelist.yml). Il faut spécifier le nom de la CVE, le paquet affecté et la raison de la mise en liste blanche.
+
+Une mise en liste blanche est **acceptable** si :
+* Clair détecte des vulnérabilités sur le paquet `linux`. En effet, le noyau utilisé par le conteneur est celui de l'hôte. On utilisera le motif `Vulnérabilité Linux`,
+* Le paquet est à jour et ne peut pas être installé dans une version différente à cause de dépendances d'autres paquets,
+* Le paquet ne peut pas être supprimé,
+* Il n'existe pas de contre-mesure à la vulnérabilité,
+* La vulnérabilité, même si elle est classée en criticité `High`, a peu de conséquences pour Picasoft. Cela peut être le cas pour une attaque par déni de service causant un usage de 100% du processeur, qui n'aura d'impact que sur Etherpad en raison des limitations de ressources.
+
On prend l'exemple de la `CVE-2020-8492 (High)` détectée par Clair lors d'un build de `pica-db-backup-rotation` ([commit](https://gitlab.utc.fr/picasoft/projets/dockerfiles/-/commit/078d448a53da4be9330fd0ac9304a7eb3a26e969), [log de Clair](https://gitlab.utc.fr/picasoft/projets/dockerfiles/-/jobs/883005))
diff --git a/template/docker-compose.yml b/template/docker-compose.yml
index 3fe38f78cab45817d669ac460d475e35829bfc64..2cdd3e63a52c4f2dd688080093f7fbadca0dbc3c 100644
--- a/template/docker-compose.yml
+++ b/template/docker-compose.yml
@@ -1,11 +1,17 @@
version: "3.7"
volumes:
+ # Name used in this file
myvolume:
- external: true # Do not delete on docker-compose down
+ # Real name listed in `docker volume ls`
+ name: <volume_name>
networks:
- mynetwork: # Best pratice: separate what doesn't need to be connected.
+ # Best pratice : put all services that do not need
+ # to be exposed on the Internet in a separate network
+ mynetwork:
+ # This is the reverse-proxy default network : put all services
+ # that need to be served via Traefik in this network
docker_default:
external: true