Priorité des variables d'environnement dans Docker Compose

Lorsque la même variable d'environnement est définie dans plusieurs sources, Docker Compose suit une règle de priorité pour déterminer la valeur de cette variable dans l'environnement de votre conteneur.

Cette page contient des informations sur le niveau de priorité que prend chaque méthode de définition des variables d'environnement.

L'ordre de priorité (du plus élevé au plus bas) est le suivant :

1. Défini en utilisant docker compose run -e dans la CLI.
2. Défini avec l'attribut environment ou env_file mais avec la valeur interpolée depuis votre shell ou un fichier d'environnement. (soit votre fichier .env par défaut, ou avec l'argument --env-file dans la CLI).
3. Défini en utilisant seulement l'attribut environment dans le fichier Compose.
4. Utilisation de l'attribut env_file dans le fichier Compose.
5. Défini dans une image de conteneur dans la directive ENV. Avoir n'importe quel paramètre ARG ou ENV dans un Dockerfile ne s'évalue que s'il n'y a pas d'entrée Docker Compose pour environment, env_file ou run --env.

Exemple simple

Dans l'exemple suivant, une valeur différente pour la même variable d'environnement dans un fichier .env et avec l'attribut environment dans le fichier Compose :

$ cat ./webapp.env
NODE_ENV=test

$ cat compose.yaml
services:
  webapp:
    image: 'webapp'
    env_file:
     - ./webapp.env
    environment:
     - NODE_ENV=production

La variable d'environnement définie avec l'attribut environment prend la priorité.

$ docker compose run webapp env | grep NODE_ENV
NODE_ENV=production

Exemple avancé

Le tableau suivant utilise VALUE, une variable d'environnement définissant la version d'une image, comme exemple.

Comment fonctionne le tableau

Chaque colonne représente un contexte à partir duquel vous pouvez définir une valeur, ou substituer une valeur pour VALUE.

Les colonnes Environnement de l'OS hôte et fichier .env sont listées uniquement à des fins d'illustration. En réalité, elles ne résultent pas en une variable dans le conteneur par elles-mêmes, mais en conjonction avec l'attribut environment ou env_file.

Chaque ligne représente une combinaison de contextes où VALUE est défini, substitué, ou les deux. La colonne Résultat indique la valeur finale pour VALUE dans chaque scénario.

Explication des résultats

Résultat 1 : L'environnement local prend la priorité, mais le fichier Compose n'est pas configuré pour répliquer cela dans le conteneur, donc aucune variable de ce type n'est définie.

Résultat 2 : L'attribut env_file dans le fichier Compose définit une valeur explicite pour VALUE donc l'environnement du conteneur est défini en conséquence.

Résultat 3 : L'attribut environment dans le fichier Compose définit une valeur explicite pour VALUE, donc l'environnement du conteneur est défini en conséquence.

Résultat 4 : La directive ENV de l'image déclare la variable VALUE, et puisque le fichier Compose n'est pas configuré pour remplacer cette valeur, cette variable est définie par l'image.

Résultat 5 : La commande docker compose run a le drapeau --env défini avec une valeur explicite, et remplace la valeur définie par l'image.

Résultat 6 : La commande docker compose run a le drapeau --env défini pour répliquer la valeur de l'environnement. La valeur de l'OS hôte prend la priorité et est répliquée dans l'environnement du conteneur.

Résultat 7 : La commande docker compose run a le drapeau --env défini pour répliquer la valeur de l'environnement. La valeur du fichier .env est sélectionnée pour définir l'environnement du conteneur.

Résultat 8 : L'attribut env_file dans le fichier Compose est défini pour répliquer VALUE de l'environnement local. La valeur de l'OS hôte prend la priorité et est répliquée dans l'environnement du conteneur.

Résultat 9 : L'attribut env_file dans le fichier Compose est défini pour répliquer VALUE de l'environnement local. La valeur du fichier .env est sélectionnée pour définir l'environnement du conteneur.

Résultat 10 : L'attribut environment dans le fichier Compose est défini pour répliquer VALUE de l'environnement local. La valeur de l'OS hôte prend la priorité et est répliquée dans l'environnement du conteneur.

Résultat 11 : L'attribut environment dans le fichier Compose est défini pour répliquer VALUE de l'environnement local. La valeur du fichier .env est sélectionnée pour définir l'environnement du conteneur.

Résultat 12 : Le drapeau --env a une priorité plus élevée que les attributs environment et env_file et est défini pour répliquer VALUE de l'environnement local. La valeur de l'OS hôte prend la priorité et est répliquée dans l'environnement du conteneur.

Résultats 13 à 15 : Le drapeau --env a une priorité plus élevée que les attributs environment et env_file et définit donc la valeur.