Ce que vous allez apprendre

• Distinguer le fichier .env racine (interpolation du YAML) de env_file (variables du conteneur)
• Savoir laquelle de environment ou env_file l'emporte en cas de valeur en double
• Fournir une valeur par défaut avec la syntaxe ${VAR:-defaut}
• Charger un fichier .env différent selon l'environnement avec --env-file
• Ne jamais committer de secrets dans un fichier .env versionné

Dans quel contexte ?

Un développeur clone le dépôt boutique-api et lance docker compose up, en pensant que la variable DB_PASSWORD définie dans son .env racine sera automatiquement visible dans le code Node.js du conteneur. Elle ne l'est pas : l'application plante avec une erreur "password authentication failed" car cette variable n'a servi qu'à interpoler le YAML, pas à alimenter le conteneur. Cette leçon explique cette distinction essentielle.

Le principe de départ : ne pas coder en dur

D'abord, une règle de base issue des applications "12-factor" : ne jamais coder en dur une valeur qui change selon l'environnement, comme un mot de passe de base de données ou une URL d'API. Ces valeurs doivent vivre en dehors du code, dans des variables d'environnement.

Premier mécanisme : le fichier .env pour l'interpolation

Compose propose un fichier .env à la racine du projet. Son rôle est précis : il remplit les ${VARIABLE} présentes DANS le fichier YAML lui-même, avant même que Compose ne parle à Docker. C'est de la simple substitution de texte dans ta configuration.

Un piège à anticiper tout de suite

Attention, ce .env racine ne finit PAS automatiquement dans le conteneur. Beaucoup de débutants pensent que placer une variable dans ce fichier suffit à la rendre disponible pour l'application — ce n'est pas le cas.

Deuxième mécanisme : env_file et environment pour le conteneur

Pour qu'une variable soit réellement disponible dans le conteneur, via process.env ou équivalent, il faut utiliser env_file ou environment. Ces deux clés injectent véritablement des variables à l'intérieur du conteneur, contrairement au .env racine qui ne fait que de l'interpolation.

Que se passe-t-il en cas de conflit ?

Une fois qu'on utilise les deux mécanismes ensemble, une question se pose naturellement : que se passe-t-il si une variable est définie à la fois par env_file et environment ? La réponse est simple : c'est toujours environment qui gagne, car c'est la déclaration la plus explicite.

Mécanisme	Où il agit	Visible dans le conteneur ?
.env racine	Interpolation du fichier YAML (${VAR})	Non, sauf s'il est repris dans environment
env_file:	Injection de tout un fichier dans le conteneur	Oui
environment:	Injection directe, clé par clé	Oui, prioritaire sur env_file

Une astuce pratique : les valeurs par défaut

Pour aller plus loin, la syntaxe ${VAR:-valeur_par_défaut} permet de fournir une valeur de secours si la variable n'est pas définie, tout en gardant la possibilité de la surcharger plus tard.

Le piège majeur à ne jamais commettre

Ne committe jamais un .env contenant de vrais secrets dans Git. Il doit systématiquement figurer dans le .gitignore, avec à la place un .env.example versionné qui documente simplement les variables attendues, sans leurs valeurs sensibles.

La prochaine leçon s'appuie directement sur ces notions pour résoudre un autre problème classique : s'assurer qu'un service ne démarre pas avant qu'un autre soit vraiment prêt.