Variables d'environnement Docker Compose : .env, env_file et priorités

Les variables d'environnement Docker Compose peuvent fournir des valeurs lors de la lecture d'une configuration ou devenir des réglages dans un conteneur. Une valeur placée dans un fichier .env n'arrive pas automatiquement jusqu'à l'application. La configuration du service doit relier ces deux étapes.

Ce guide distingue .env, --env-file, env_file et environment, puis propose un petit exemple dont vous pouvez examiner les valeurs finales. Il couvre les priorités, les variables absentes, les signes dollar et les modifications qui nécessitent de recréer un conteneur. Les valeurs utilisées sont des réglages de test, sans identifiants réels.

Distinguer les entrées de Compose de l'environnement du conteneur

La présentation des variables par Docker distingue l'interpolation de la configuration du conteneur. L'interpolation remplace des expressions comme ${ENV_DEMO_TAG} lorsque Compose construit son modèle applicatif. Le nom d'image, le port ou la valeur obtenue fait ensuite partie de ce modèle.

• .env : une source par défaut de valeurs d'interpolation pour la CLI Compose.
• --env-file : une option de la CLI qui sélectionne explicitement un fichier d'entrée pour l'interpolation.
• env_file : un attribut de service qui fournit des variables à ses conteneurs.
• environment : des entrées explicites pour l'environnement du service, avec des valeurs littérales ou des expressions interpolées.

Un fichier peut servir aux deux usages si vous le configurez explicitement, mais les rôles restent distincts. Le guide de l'environnement des conteneurs présente ces attributs. Documentez les entrées attendues avec le projet ; notre guide de l'environnement de développement couvre cette organisation.

Construire un exemple avec .env et env_file

Créez un nouveau répertoire de test et enregistrez-y les trois fichiers suivants. Utilisez la CLI Docker Compose avec la commande docker compose. L'exemple décrit un conteneur Linux sans ports, fichiers hôtes montés ni accès réseau. Compose peut le valider sans démarrer le moteur Docker.

Enregistrez d'abord les entrées d'interpolation dans .env. Vérifiez que l'éditeur n'ajoute pas discrètement une extension .txt :

ENV_DEMO_TAG=3.22
ENV_DEMO_MODE=development
ENV_DEMO_LABEL=compose-lab
ENV_DEMO_UNUSED=not-passed

Enregistrez ensuite container.env. Sa valeur APP_MODE entre volontairement en conflit avec celle du service pour rendre la priorité visible :

APP_MODE=from-service-file
LOG_LEVEL=info

Enfin, enregistrez compose.yaml :

services:
  inspect:
    image: "alpine:${ENV_DEMO_TAG:-3.22}"
    network_mode: none
    env_file:
      - ./container.env
    environment:
      APP_MODE: "${ENV_DEMO_MODE:-development}"
      APP_LABEL: "${ENV_DEMO_LABEL:?Set ENV_DEMO_LABEL in the input file}"
    command:
      - sh
      - -c
      - 'printf "mode=%s label=%s log=%s\n" "$$APP_MODE" "$$APP_LABEL" "$$LOG_LEVEL"'

Le tag de l'image provient de ENV_DEMO_TAG. APP_MODE et APP_LABEL sont transmis explicitement au conteneur ; LOG_LEVEL provient de container.env. ENV_DEMO_UNUSED est une entrée d'interpolation sans usage dans le service : elle n'apparaît donc pas dans son environnement.

L'attribut command appelle sh explicitement. Compose ne fournit pas automatiquement un shell à chaque commande. Les signes dollar doublés conservent les références aux variables pour que ce shell les développe dans le conteneur.

Examiner la configuration résolue avant l'exécution

Exécutez ces commandes depuis le répertoire de test. Ne lancez la seconde que si la première réussit :

docker compose -p env-lab-20261030 --env-file .env -f compose.yaml config --quiet
docker compose -p env-lab-20261030 --env-file .env -f compose.yaml config --format json

La commande config valide et résout le modèle. Recherchez l'image alpine:3.22 et les valeurs APP_MODE=development, APP_LABEL=compose-lab et LOG_LEVEL=info dans l'environnement du service. Si votre shell définit déjà des variables ENV_DEMO_, le résultat peut différer. Utilisez un shell de test isolé ou retirez volontairement ces valeurs de test avant la comparaison.

Nous avons vérifié ce modèle et les cas de priorité avec Compose v5.1.4. Cela valide la résolution de la configuration, pas l'exécution du conteneur. Ne copiez pas une sortie de production de config ou config --environment dans un ticket : elle peut révéler des identifiants. Examinez uniquement les valeurs nécessaires et masquez les données sensibles.

Pour vérifier vous-même le comportement attendu, confirmez que le contexte Docker sélectionné correspond à un hôte hors production avec un moteur accessible pour conteneurs Linux. Arrêtez-vous si l'un de ces contrôles échoue ; sinon, lancez le service jetable :

docker context show
docker version
docker compose -p env-lab-20261030 --env-file .env -f compose.yaml run --rm --no-deps inspect

L'image peut être téléchargée si elle est absente. Cette exécution ponctuelle supprime ensuite son conteneur. Avec les fichiers de base et sans surcharge du shell, la sortie attendue est :

mode=development label=compose-lab log=info

Alpine 3.22 est une branche d'exemple, sans prétention d'être la plus récente. Consultez son calendrier de support et choisissez une image maintenue et approuvée pour votre application.

Suivre les priorités à chaque étape

Pour l'interpolation, le shell peut remplacer les valeurs des fichiers. L'option --env-file rend explicite le fichier choisi ; si vous en indiquez plusieurs, les derniers peuvent remplacer les valeurs des précédents. Le guide de l'interpolation précise la recherche de .env et les règles du répertoire de projet. En automatisation, utilisez des chemins explicites plutôt que de dépendre du répertoire courant de l'appelant.

Pour le conteneur, une surcharge ponctuelle avec run -e est prioritaire. Les entrées environment du service remplacent celles de env_file, même si elles sont vides ou non résolues ; les valeurs ENV de l'image servent de valeurs par défaut lorsqu'aucun réglage prioritaire ne les remplace. Les valeurs du shell ou du fichier d'interpolation doivent toujours être reliées au service. La référence des priorités détaille les combinaisons.

Ici, environment définit APP_MODE à partir de ENV_DEMO_MODE et remplace la valeur contradictoire de container.env. Pour la modifier dans un seul nouveau conteneur de test :

docker compose -p env-lab-20261030 --env-file .env -f compose.yaml run --rm --no-deps -e APP_MODE=one-off inspect

Le mode attendu est one-off. Cette commande ne réécrit pas les fichiers et ne modifie pas un conteneur existant. Une variable du shell, un fichier d'entrée et une entrée d'environnement du service ne sont pas des emplacements interchangeables.

Gérer les valeurs absentes et les signes dollar

La référence de syntaxe distingue les variables non définies des chaînes vides :

• ${VAR:-fallback} utilise la valeur de repli si VAR est absente ou vide.
• ${VAR-fallback} l'utilise seulement si VAR est absente.
• ${VAR:?message} arrête la résolution si VAR est absente ou vide.
• ${VAR?message} refuse une variable absente, mais accepte une valeur vide.

L'expression obligatoire de APP_LABEL fait échouer la configuration dès qu'une étiquette manque. Sans valeur par défaut ni expression obligatoire, une substitution non résolue peut devenir une chaîne vide après un avertissement. La configuration peut alors sembler correcte tout en produisant un mauvais comportement.

Utilisez $$ lorsqu'un signe dollar doit survivre à l'interpolation Compose. Cela ne suffit pas à provoquer l'expansion dans le conteneur : un shell ou l'application doit s'en charger. Placez entre guillemets les valeurs qui ressemblent à des booléens, comme "false", pour les conserver sous forme de chaînes YAML. Pour les signes dollar ou guillemets littéraux dans un env_file de service, Compose 2.30.0 et versions ultérieures accepte aussi format: raw ; consultez la référence env_file avant de modifier l'analyse du fichier.

Choisir explicitement les fichiers de chaque environnement

Enregistrez ce fichier séparé sous le nom staging.env :

ENV_DEMO_MODE=staging
ENV_DEMO_LABEL=staging-lab

Résolvez le modèle avec le fichier de base, puis les surcharges de préproduction :

docker compose -p env-lab-20261030 --env-file .env --env-file staging.env -f compose.yaml config --format json

Sans surcharge du shell, le service obtient APP_MODE=staging et APP_LABEL=staging-lab. Le tag de l'image provient toujours de .env. Cette opération sélectionne une configuration ; elle ne crée ni compte, réseau, base de données ni périmètre de facturation isolé. Les recommandations de Docker encouragent des entrées distinctes, mais vous devez définir les accès de chaque environnement.

Séparer les secrets des paramètres de construction

Le nom .env ne chiffre pas le contenu d'un fichier. Gardez les vrais identifiants hors du contrôle de version et utilisez des valeurs fictives dans les exemples partagés. Pour les conteneurs Linux compatibles, les secrets Compose peuvent donner à un service accès à un fichier secret monté. L'application doit savoir le lire et la source sur l'hôte doit rester protégée. Ce mécanisme n'assure ni rotation automatique ni protection contre un administrateur de l'hôte.

Les ARG de construction et les valeurs d'environnement à l'exécution ont également des rôles distincts. La documentation des variables de construction explique pourquoi un ARG ne devient pas automatiquement une variable du conteneur et pourquoi ni ARG ni ENV ne conviennent au passage de secrets de construction. Notre guide de sécurité cloud replace les identifiants dans le contrôle des accès.

Diagnostiquer la valeur réellement reçue par l'application

1. Valeur inattendue : vérifiez les surcharges du shell, les fichiers sélectionnés et l'environnement du service avant de modifier l'image.
2. Fichier introuvable : vérifiez le répertoire courant pour --env-file et celui du fichier Compose pour les chemins env_file du service.
3. Variable absente dans le conteneur : assurez-vous que environment ou env_file la fournit. Une entrée .env seule ne suffit pas.
4. Fichier modifié, application inchangée : compose restart n'applique pas les changements d'environnement du conteneur. Un compose up vérifié peut recréer un service dont la configuration a changé ; prévoyez l'interruption et la gestion de l'état applicatif.
5. Fonctionne avec Compose, échoue ailleurs : ne supposez pas que l'interpolation Compose existe avec docker run --env-file ou docker stack deploy. Suivez le comportement documenté de l'outil cible.

Consignez la version de Compose, les fichiers sélectionnés et les réglages non secrets attendus avec l'application. Un collègue doit pouvoir résoudre le même modèle sans dépendre d'un état du shell non documenté.