Docker Compose : env_file, environment et .env, qui fait quoi
Guide env_file de Docker Compose
Docker Compose : env_file vs environment vs .env, expliqués | We.Inc
Ce que font env_file, environment et le fichier .env dans Docker Compose, quelle valeur l'emporte en cas de conflit et comment fonctionne l'interpolation ${VAR:-default}, avec un résolveur.
Dans Docker Compose, env_file charge un fichier de lignes KEY=value dans le conteneur d'un service. L'attribut environment définit des variables du conteneur directement et l'emporte sur env_file quand les deux nomment la même clé. Le fichier .env placé à côté de compose.yaml est différent : Compose le lit pour remplir les placeholders ${VAR} dans le YAML lui-même.
Trois façons de fournir des variables à Compose
Mécanisme
Portée
Atteint le conteneur ?
.env à côté de compose.yaml
Interpolation de ${VAR} dans le fichier Compose
Seulement si un service y fait référence
env_file: sur un service
Le conteneur de ce service
Oui, chaque ligne
environment: sur un service
Le conteneur de ce service
Oui, et il l'emporte sur env_file
--env-file en ligne de commande
Remplace le .env par défaut pour l'interpolation
Seulement si référencé
La confusion vient du nom : un fichier appelé .env et un attribut appelé env_file semblent désigner la même chose, mais l'un configure le fichier Compose et l'autre configure un conteneur. Utilisez le résolveur pour voir quelle source l'emporte pour une variable, puis essayez les formes d'interpolation avec une variable définie, vide ou non définie.
Cochez chaque endroit où votre variable est définie et tapez la valeur qu'elle y a.
Le résolveur parcourt depuis le haut la liste de priorité documentée par Docker et montre la valeur finale reçue par le conteneur.
Dans le testeur d'interpolation, choisissez une forme comme ${VAR:-default}, indiquez si VAR est définie, vide ou non définie, et lisez le résultat.
Lancez docker compose config dans votre projet pour confirmer ce que Compose a réellement résolu.
Lancez docker compose config --environment pour afficher les variables utilisées par Compose pour l'interpolation. Cela règle la plupart des débats en quelques secondes.
Marquez les fichiers env optionnels avec required: false (Compose 2.24.0 et suivants) pour qu'un fichier de surcharge local manquant n'arrête pas la stack.
Écrivez $$ quand vous avez besoin d'un signe dollar littéral dans compose.yaml, par exemple dans un mot de passe ou une commande shell.
Mettez les booléens entre guillemets dans la map environment, comme SHOW: "true", pour que YAML ne les transforme pas en valeurs true et false.
Questions fréquentes
Quelle est la différence entre env_file et environment ?
Les deux placent des variables dans le conteneur d'un service. env_file les lit depuis un ou plusieurs fichiers, environment les liste dans compose.yaml. Quand la même clé apparaît dans les deux, la valeur de environment l'emporte, même si elle est vide.
Compose transmet-il automatiquement mon fichier .env aux conteneurs ?
Non. Le fichier .env du projet sert uniquement à substituer ${VAR} dans le fichier Compose. Une variable n'atteint un conteneur que si un service la nomme sous environment, ou charge le fichier avec env_file.
Où Compose cherche-t-il le fichier .env ?
Dans le répertoire du projet, c'est-à-dire le dossier indiqué avec --project-directory, sinon le dossier du premier fichier -f, sinon votre dossier courant. Utilisez --env-file pour pointer vers un autre fichier ; s'il y en a plusieurs, les derniers remplacent les premiers.
Les chemins de env_file sont-ils relatifs à l'endroit où je lance la commande ?
Non. Les chemins relatifs de env_file sont résolus à partir du dossier qui contient le fichier Compose, donc la stack fonctionne quel que soit l'endroit d'où vous la lancez.
Que devient ${VAR} quand VAR n'est pas définie ?
Compose affiche un avertissement et substitue une chaîne vide. Utilisez ${VAR:-fallback} pour fournir une valeur par défaut, ou ${VAR:?message} pour vous arrêter plutôt sur une erreur.
La liste de priorité, de haut en bas
Docker documente cinq niveaux. Une valeur passée avec docker compose run -e est la plus forte. Viennent ensuite environment ou env_file quand la valeur est interpolée depuis votre shell ou un fichier d'environnement, puis une valeur littérale sous environment, puis une valeur issue de env_file, et en dernier une ligne ENV intégrée à l'image.
Remarquez qu'un seul de ces niveaux concerne le fichier .env, et seulement de façon indirecte : il alimente le niveau deux par l'interpolation. Une valeur présente dans .env qu'aucun service ne mentionne n'apparaît jamais dans un conteneur.
Clés sans valeur
Un nom seul sous environment, comme - API_TOKEN sans signe égal, copie la valeur depuis le shell qui exécute Compose. Si le shell ne l'a pas, la variable reste non définie.
Dans un env_file, une ligne contenant seulement une clé annule cette variable et la retire de l'environnement du conteneur, ce qui est pratique pour effacer volontairement une valeur définie par l'image.
Toutes les formes d'interpolation
Ce que donne chaque forme pour une VAR définie, vide ou non définie
Forme
VAR=abc
VAR vide
VAR non définie
${VAR} ou $VAR
vide, avec un avertissement
${VAR:-default}
${VAR-default}
${VAR:?msg}
erreur msg
erreur msg
${VAR?msg}
erreur msg
${VAR:+other}
${VAR+other}
un $ littéral
un $ littéral
un $ littéral
Fichiers Compose à copier
env_file avec surcharges dans environment
Les réglages partagés viennent de fichiers ; les entrées de environment l'emportent pour les clés qu'elles nomment. Le fichier local est optionnel.
.env du projet utilisé uniquement pour l'interpolation
Ces deux valeurs remplissent des placeholders dans compose.yaml. Aucune n'atteint un conteneur sauf si un service la mentionne.
Utiliser ces valeurs dans compose.yaml
Le tag de l'image et le port publié viennent de .env ; le mot de passe doit être défini, sinon Compose s'arrête avec un message clair.
Vérifier ce que Compose a résolu
config affiche le modèle final avec chaque variable remplie ; --environment liste les valeurs utilisées pour la substitution.
Quelle valeur l'emporte ?
La variable APP_MODE est définie aux endroits cochés ci-dessous.
Où la variable est définie
Valeur
Le conteneur reçoit APP_MODE={v} depuis : {n}
Définie nulle part, donc APP_MODE est absente du conteneur.
Testeur d'interpolation
Expression
VAR est
définie mais vide
Valeur de VAR
Résultat : {v}
Résultat : une chaîne vide
Compose s'arrête avec l'erreur : {v}
Résultat : une chaîne vide, et Compose affiche un avertissement