⚠️ Traduction non officielle - Cette documentation est une traduction communautaire non officielle de Docker.

Définir, utiliser et gérer les variables dans un fichier Compose avec l'interpolation

Table des matières

Un fichier Compose peut utiliser des variables pour offrir plus de flexibilité. Si vous souhaitez basculer rapidement entre les tags d'image pour tester plusieurs versions, ou ajuster une source de volume à votre environnement local, vous n'avez pas besoin d'éditer le fichier Compose à chaque fois, vous pouvez simplement définir des variables qui insèrent des valeurs dans votre fichier Compose au moment de l'exécution.

L'interpolation peut également être utilisée pour insérer des valeurs dans votre fichier Compose au moment de l'exécution, qui sont ensuite utilisées pour transmettre des variables dans l'environnement de votre conteneur.

Voici un exemple simple :

$ cat .env
TAG=v1.5
$ cat compose.yaml
services:
  web:
    image: "webapp:${TAG}"

Lorsque vous exécutez docker compose up, le service web défini dans le fichier Compose interpole l'image webapp:v1.5 qui a été définie dans le fichier .env. Vous pouvez vérifier cela avec la commande config, qui affiche votre configuration d'application résolue sur le terminal :

$ docker compose config
services:
  web:
    image: 'webapp:v1.5'

Syntaxe d'interpolation

L'interpolation est appliquée pour les valeurs non quotées et quotées avec des guillemets doubles. Les expressions avec accolades (${VAR}) et sans accolades ($VAR) sont prises en charge.

Pour les expressions avec accolades, les formats suivants sont pris en charge :

  • Substitution directe
    • ${VAR} -> valeur de VAR
  • Valeur par défaut
    • ${VAR:-default} -> valeur de VAR si définie et non vide, sinon default
    • ${VAR-default} -> valeur de VAR si définie, sinon default
  • Valeur requise
    • ${VAR:?error} -> valeur de VAR si définie et non vide, sinon quitte avec erreur
    • ${VAR?error} -> valeur de VAR si définie, sinon quitte avec erreur
  • Valeur alternative
    • ${VAR:+replacement} -> replacement si VAR est définie et non vide, sinon vide
    • ${VAR+replacement} -> replacement si VAR est définie, sinon vide

Pour plus d'informations, voir Interpolation dans la spécification Compose.

Façons de définir des variables avec l'interpolation

Docker Compose peut interpoler des variables dans votre fichier Compose à partir de plusieurs sources.

Notez que lorsque la même variable est déclarée par plusieurs sources, la priorité s'applique :

  1. Variables de votre environnement shell
  2. Si --env-file n'est pas défini, variables définies par un fichier .env dans le répertoire de travail local (PWD)
  3. Variables d'un fichier défini par --env-file ou un fichier .env dans le répertoire du projet

Vous pouvez vérifier les variables et valeurs utilisées par Compose pour interpoler le modèle Compose en exécutant docker compose config --environment.

Fichier .env

Un fichier .env dans Docker Compose est un fichier texte utilisé pour définir des variables qui doivent être rendues disponibles pour l'interpolation lors de l'exécution de docker compose up. Ce fichier contient généralement des paires clé-valeur de variables, et il vous permet de centraliser et gérer la configuration en un seul endroit. Le fichier .env est utile si vous avez plusieurs variables que vous devez stocker.

Le fichier .env est la méthode par défaut pour définir des variables. Le fichier .env doit être placé à la racine du répertoire du projet à côté de votre fichier compose.yaml. Pour plus d'informations sur le formatage d'un fichier d'environnement, voir Syntaxe des fichiers d'environnement.

Exemple de base :

$ cat .env
## définir COMPOSE_DEBUG basé sur DEV_MODE, par défaut false
COMPOSE_DEBUG=${DEV_MODE:-false}

$ cat compose.yaml 
  services:
    webapp:
      image: my-webapp-image
      environment:
        - DEBUG=${COMPOSE_DEBUG}

$ DEV_MODE=true docker compose config
services:
  webapp:
    environment:
      DEBUG: "true"

Informations supplémentaires

  • Si vous définissez une variable dans votre fichier .env, vous pouvez la référencer directement dans votre compose.yaml avec l'attribut environment. Par exemple, si votre fichier .env contient la variable d'environnement DEBUG=1 et que votre fichier compose.yaml ressemble à ceci :

     services:
   webapp:
     image: my-webapp-image
     environment:
       - DEBUG=${DEBUG}

    Docker Compose remplace ${DEBUG} par la valeur du fichier .env

    Important

    Soyez conscient de la priorité des variables d'environnement lors de l'utilisation de variables dans un fichier .env comme variables d'environnement dans l'environnement de votre conteneur.

  • Vous pouvez placer votre fichier .env dans un emplacement autre que la racine du répertoire de votre projet, puis utiliser l'option --env-file dans la CLI pour que Compose puisse s'y rendre.

  • Votre fichier .env peut être remplacé par un autre fichier .env s'il est substitué avec --env-file.

Important

La substitution à partir de fichiers .env est une fonctionnalité de Docker Compose CLI.

Elle n'est pas prise en charge par Swarm lors de l'exécution de docker stack deploy.

Syntaxe du fichier .env

Les règles de syntaxe suivantes s'appliquent aux fichiers d'environnement :

  • Les lignes commençant par # sont traitées comme des commentaires et ignorées.
  • Les lignes vides sont ignorées.
  • Les valeurs non quotées et quotées avec des guillemets doubles (") ont l'interpolation appliquée.
  • Chaque ligne représente une paire clé-valeur. Les valeurs peuvent être optionnellement quotées.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
  • Les commentaires en ligne pour les valeurs non quotées doivent être précédés d'un espace.
    • VAR=VAL # comment -> VAL
    • VAR=VAL# not a comment -> VAL# not a comment
  • Les commentaires en ligne pour les valeurs quotées doivent suivre le guillemet fermant.
    • VAR="VAL # not a comment" -> VAL # not a comment
    • VAR="VAL" # comment -> VAL
  • Les valeurs entre guillemets simples (') sont utilisées littéralement.
    • VAR='$OTHER' -> $OTHER
    • VAR='${OTHER}' -> ${OTHER}
  • Les guillemets peuvent être échappés avec \.
    • VAR='Let\'s go!' -> Let's go!
    • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
  • Les séquences d'échappement shell communes incluant \n, \r, \t, et \\ sont prises en charge dans les valeurs quotées avec des guillemets doubles.
    • VAR="some\tvalue" -> some value
    • VAR='some\tvalue' -> some\tvalue
    • VAR=some\tvalue -> some\tvalue

Substituer avec --env-file

Vous pouvez définir des valeurs par défaut pour plusieurs variables d'environnement, dans un fichier .env puis passer le fichier comme argument dans la CLI.

L'avantage de cette méthode est que vous pouvez stocker le fichier n'importe où et le nommer de manière appropriée, par exemple, Ce chemin de fichier est relatif au répertoire de travail actuel où la commande Docker Compose est exécutée. Passer le chemin du fichier se fait en utilisant l'option --env-file :

$ docker compose --env-file ./config/.env.dev up

Informations supplémentaires

  • Cette méthode est utile si vous voulez temporairement remplacer un fichier .env qui est déjà référencé dans votre fichier compose.yaml. Par exemple, vous pourriez avoir différents fichiers .env pour la production (.env.prod) et les tests (.env.test). Dans l'exemple suivant, il y a deux fichiers d'environnement, .env et .env.dev. Les deux ont des valeurs différentes définies pour TAG. 
    $ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat compose.yaml
services:
  web:
    image: "webapp:${TAG}"
    Si --env-file n'est pas utilisé dans la ligne de commande, le fichier .env est chargé par défaut : 
    $ docker compose config
services:
  web:
    image: 'webapp:v1.5'
    Passer l'argument --env-file remplace le chemin de fichier par défaut : 
    $ docker compose --env-file ./config/.env.dev config
services:
  web:
    image: 'webapp:v1.6'
    Lorsqu'un chemin de fichier invalide est passé comme argument --env-file, Compose retourne une erreur : 
    $ docker compose --env-file ./doesnotexist/.env.dev  config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
  • Vous pouvez utiliser plusieurs options --env-file pour spécifier plusieurs fichiers d'environnement, et Docker Compose les lit dans l'ordre. Les fichiers ultérieurs peuvent remplacer les variables des fichiers précédents. 
    $ docker compose --env-file .env --env-file .env.override up
  • Vous pouvez remplacer des variables d'environnement spécifiques depuis la ligne de commande lors du démarrage des conteneurs. 
    $ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database

Fichier .env local versus fichier .env du <répertoire de projet>

Un fichier .env peut également être utilisé pour déclarer des variables d'environnement prédéfinies utilisées pour contrôler le comportement de Compose et les fichiers à charger.

Lorsqu'exécuté sans drapeau --env-file explicite, Compose recherche un fichier .env dans votre répertoire de travail (PWD) et charge les valeurs à la fois pour l'auto-configuration et l'interpolation. Si les valeurs de ce fichier définissent la variable prédéfinie COMPOSE_FILE, ce qui résulte en un répertoire de projet défini vers un autre dossier, Compose chargera un second fichier .env, s'il est présent. Ce second fichier .env a une priorité plus faible.

Ce mécanisme permet d'invoquer un projet Compose existant avec un ensemble personnalisé de variables comme substitutions, sans avoir besoin de passer des variables d'environnement par la ligne de commande.

$ cat .env
COMPOSE_FILE=../compose.yaml
POSTGRES_VERSION=9.3

$ cat ../compose.yaml 
services:
  db:
    image: "postgres:${POSTGRES_VERSION}"
$ cat ../.env
POSTGRES_VERSION=9.2

$ docker compose config
services:
  db:
    image: "postgres:9.3"

Substituer depuis le shell

Vous pouvez utiliser des variables d'environnement existantes de votre machine hôte ou de l'environnement shell où vous exécutez les commandes docker compose. Cela vous permet d'injecter dynamiquement des valeurs dans votre configuration Docker Compose au moment de l'exécution. Par exemple, supposons que le shell contient POSTGRES_VERSION=9.3 et que vous fournissez la configuration suivante :

db:
  image: "postgres:${POSTGRES_VERSION}"

Lorsque vous exécutez docker compose up avec cette configuration, Compose recherche la variable d'environnement POSTGRES_VERSION dans le shell et substitue sa valeur. Pour cet exemple, Compose résout l'image en postgres:9.3 avant d'exécuter la configuration.

Si une variable d'environnement n'est pas définie, Compose substitue par une chaîne vide. Dans l'exemple précédent, si POSTGRES_VERSION n'est pas définie, la valeur pour l'option image est postgres:.

Note

postgres: n'est pas une référence d'image valide. Docker attend soit une référence sans tag, comme postgres qui utilise par défaut la dernière image, ou avec un tag tel que postgres:15.