{{tag>sysadmin docker docker-compose}}

====== docker-compose ======

docker-compose fait parti d'un ensemble d'outils de l'environnement Docker qui comprend:
  * docker engine: le moteur docker
  * docker machine
  * docker swarm

docker-compose est un orchestrateur. Lancer un nombre important de conteneurs n'est pas forcément simple. Il faut:
  * Coordonner les conteneurs;
  * Gérer les dépendances (volumes, réseaux, partages de fichiers etc).

docker-compose orchestre/gère des services. Un service est composé d'un ou plusieurs conteneurs.


docker-compose est paramétré via un fichier texte formaté en YAML, facilement lisible et pouvant être intégré à un outil de révision (versioning) tel que git.

===== Installation =====

<code bash>
apt-get install docker-compose
</code>

===== Commandes ======

Construire les images
<code bash>
docker-compose build
</code>

Lance l’exécution des services définis, construit les images si nécessaire
<code bash>
docker-compose up -d
</code>

Pour gérer les services:
<code bash>
#etat des services
docker-compose ps

# démarrage / arret / destruction d'un service
docker-compose start srv_name
docker-compose stop srv_name
docker-compose rm srv_name
</code>

===== Variables =====

Le docker-compose.yml peut comporter des variables qui seront résolues en fonction des valeurs définies dans l'environnement. Par défaut le commande docker-compose lit les valeur du fichier .env s'il existe.

<file txt .env>
COMPOSE_PROJECT_NAME=test
HOSTNAME=localhost
</file>

Dans cet exemple deux variables sont définies, on récupère leur valeur au sein du fichier docker-compose.yml via la syntaxe **%%${MA_VARIABLE}%%**:
<file>
${HOSTNAME}
</file>

Pour chaque service, on peut redéfinir le fichier contenant les variables d'environnement:
<file>
services:
     web:
       env_file: variables.env
</file>

===== Éléments de syntaxe =====

<note warning>
Le fichier docker compose est introduit par un numéro de version majeur (il est également précisé dans la documentation officielle de préciser la version mineure) les mots clés utilisés/disponibles peuvent fortement varier en fonction de la version utilisée.
</note>

==== Directive environnement ====

https://docs.docker.com/compose/compose-file/compose-file-v3/#environment


===== Vérifier la syntaxe =====

Après toute modification du fichier, la syntaxe et la complétions des variables du fichier docker-compose.yml peuvent

<code bash>
docker-compose config
</code>

La commande retourne sur la sortie standard les valeurs définies dans le fichier: les variables utilisés dans le fichier sont expansées.


===== Scaling =====

docker-compose permet le passage à l’échelle (scaling) via l'option scale de la commande up:

<code bash>
# lance 3 instances du service srv_name
docker-compose up -d --scale srv_name=3
</code>


<note>
Chaque conteneur doit avoir un nom unique. Le passage à l'échelle échouera si l'utilisateur a défini un nom de conteneur via la directive **container-name**. Le nom du conteneur créé lors de l'opération de mise à l'échelle est la concaténation du nom de projet, du nom de service et d'un numéro d'instance. Il est possible de redéfinir le nom de projet via la variable d'environnement **COMPOSE_PROJECT_NAME**. Par défaut le nom de projet correspond au nom du répertoire parent.
</note>


===== Références =====

  * https://docs.docker.com/compose/compose-file/
  * https://docs.docker.com/compose/compose-file/compose-file-v3/
  * https://docs.docker.com/compose/compose-file/compose-versioning/#version-3
  * https://docs.docker.com/compose/compose-file/compose-file-v3/#environment