## 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 : elles 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/)

## Se baser sur un autre Dockerfile ?

Tous les services tournant sur l'infrastructure de Picasoft sont voués à être pris en charge par ce dépôt.

Il y a plusieurs cas.

### Je veux faire tourner un service existant, tel quel

Si un service existant a une image Docker officielle, référencée sur le Docker Hub, et qu'elle nous suffit, on s'en servira telle quel dans le `docker-compose.yml`.

### Je veux customiser un service existant

Supposons que l'image Docker officielle ne nous convienne pas, que l'on soit obligé de la modifier pour régler des problèmes de sécurité, ou tout simplement qu'on veuille l'étendre, il faut créer un Dockerfile plus complet. Il y a deux solutions :

* Soit on part de l'image officielle, avec un `FROM`, et on travaille dessus en rajoutant des fichiers, en enlevant des paquets... Cette solution a l'inconvénient de multiplier les *layers* inutiles, et d'augmenter la taille de l'image.
* Soit on copie le Dockerfile de l'image officielle (c'est le cas pour [Mattermost](../pica-mattermost)), et on fait nos modifications. Cette solution a pour inconvénient de devoir se synchroniser avec les modifications du Dockerfile officiel à chaque mise à jour, s'il contient des améliorations ou corrections importantes.

### Je veux écrire un Dockerfile de zéro.

Allez-y ! :D

## Dockerfile

Une [série de recommendations](https://wiki.picasoft.net/doku.php?id=technique:docker:tips) est disponible ici pour l'écriture des Dockerfile.

## Image de base

Préférez vous baser sur une image Alpine (peu de paquets, donc peu de vulnérabilités) ou Debian.
Pour Debian, préférez la version stable la plus récente possible (Buster plutôt que Stretch) pour mitiger d'emblée un grand nombre de vulnérabilités.

Préférez également les versions `slim`, qui contiennent moins de paquets et suffisent souvent.

Pour les services basés sur un langage interprété comme Python, utilisez l'image officielle en appliquant les principes précédents.

## Builds reproductibles

L'idée derrière un build "reproductible", c'est que si je me rends sur un ancien commit de ce dépôt et que je lance un `docker build` dans un dossier, comme `pica-mattermost`, l'image finale doit être la même quel que soit le temps écoulé depuis ce commit. Pourquoi ? Pour pouvoir relancer le build d'une ancienne version et la remettre en production en cas de problème.

Souvent, un Dockerfile va récupérer du code sur un dépôt Git, ou encore un binaire sur un site de téléchargement de releases.
Il est fortement déconseillé de faire un `git clone` ou un `wget` de la dernière version (`latest`, `master`...), ce qui rend le build non reproductible et dépendant de cette dernière version.

Il est donc important de gérer la version du service en question, par exemple avec une variable `ARG SERVICE_VERSION=1.0.1` qui sera ré-utilisée dans l'URL de téléchargement.

En outre il existe deux solutions pour récupérer du code existant, versionné sur un dépôt Git distant :
* Installer Git dans le Dockerfile, utiliser un `git clone` puis un `git checkout <tag>` sur la version souhaitée et copier le code dans l'image.
* Utiliser un [submodule](https://git-scm.com/book/fr/v2/Utilitaires-Git-Sous-modules) dans le dossier du service, en particulier si le dépôt où se trouve le code est de petite taille et qu'il n'utilise pas les tags. En effet, comme un submodule est lié à un numéro de commit, chaque commit de ce dépôt sera associé à un commit précis du dépôt distant. On peut donc retrouver l'état du code distant avec le numéro de commit du submodule associé au commit local.

## 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:
  exemple:
    [...]
    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 re-créations, alors on utilise des volumes Docker. C'est typiquement le cas pour le dossier `/var/lib/postgresql/data` d'une base PostgreSQL, qui ne doit pas supprimer les données à chaque re-création du conteneur.

Exemple :

```yaml
[...]
volumes:
  # Nom du volume Docker
  db:
    # On spécifie le nom exact
    name: db

  services:
    exemple:
      volumes:
        # On fait référence au "db" défini ci-dessus, et on le monte sur /mount_point
        - db:/mount_point
```

Il est suggéré d'éviter les volumes déclarés `external` :
* Un volume créé en dehors de Compose peut être utilisé sans être déclaré `external` ;
* En revanche un volume non-créé et déclaré `external` fera échouer les commandes Compose.

## 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
    labels:
      # Traefik va prendre ce conteneur en compte
      traefik.enable: true
      # Il redirigera vers ce port, exposé par le conteneur
      traefik.port: <port>
      # Lorsque l'utilisateur consulte cette URL
      traefik.frontend.rule: <exemple>.picasoft.net
```

## Système init

Tous les systèmes Linux ont un système dit `init`, correspondant au processus avec le premier PID (1). Ce processus est le parent de tous les autres, et doit transmettre les signaux qu'il reçoit à ses enfants (par exemple, un signal de terminaison).

Quand vous lancez un conteneur avec un script Shell ou Bash comme entrypoint, ce script a le PID 1.
S'il démarre ensuite l'application, il ne transmettra pas le signal de terminaison à ses enfants (fonctionnement normal des scripts shell).

Le souci, c'est qu'un `docker stop` enverra un signal `SIGTERM` au script d'entrypoint, mais il ne sera pas transmis au service en lui-même, qui se terminera brutalement par un `SIGKILL` après expiration du timeout.

Compose, depuis la version 3.7, adresse ce problème avec une directive très simple :
```
services:
  exemple:
    init: true
```

[Plus d'informations sur ce lien](https://hynek.me/articles/docker-signals/) et [sur la documentation de Compose](https://docs.docker.com/compose/compose-file/#init).

## 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.

Ainsi, la compromission d'un service dans un réseau particulier ne permet pas d'accéder aux autres services qui ne seraient pas exposés sur internet.

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.

Ce qui nous donnerait quelque chose comme :

```yaml
networks:
  # C'est le réseau dans lequel se trouve
  # Traefik sur toutes les machines.
  docker_default:
    external: true
  # Ce réseau est créé uniquement pour
  # ce fichier Compose.
  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
  # La base de donnée n'est que dans son réseau, et n'est donc
  # pas accessible depuis Internet.
  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.

Par exemple, pour pouvoir se connecter au serveur LDAP de manière sécurisée, on utilise LDAPS, mais on ne passe pas par Traefik, qui ne gère que les services web.

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 fichier Compose du dépôt.

## Divers

On utilisera une version récente dans les fichiers `docker-compose.yml`, et au minimum la 3.7 pour profiter des fonctionnalités présentes dans ce guide.

```yaml
version: '3.7'
```

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.