Docker Compose : pourquoi ma variable .env est-elle absente du conteneur ?

Un fichier .env placé près de compose.yaml sert d’abord à remplacer ${VARIABLE} dans la configuration Compose. Il ne transmet pas automatiquement toutes ses valeurs aux processus du conteneur. C’est la distinction à vérifier avant de modifier l’application.

Identifier où la valeur disparaît

Depuis le dossier du projet, vérifiez que Compose lit le bon fichier :

docker compose config --quiet
docker compose config --environment

config --environment montre les valeurs utilisées pour l’interpolation. Ne partagez pas cette sortie si elle contient des secrets. Si la variable manque ici, vérifiez le dossier de lancement, le nom du fichier, l’orthographe et les éventuelles options --env-file ou -f.

Si l’interpolation est correcte mais que l’application ne voit rien, vérifiez la configuration du service concerné. La commande suivante affiche le modèle résolu et peut révéler des secrets :

docker compose config

Cherchez le service, puis sa section environment ou env_file. Évitez de copier la sortie dans un ticket sans la nettoyer.

Transmettre explicitement la variable

Supposons ce fichier local .env :

APP_MODE=development

Pour transmettre cette seule valeur au service app :

services:
  app:
    image: mon-application:locale
    environment:
      APP_MODE: ${APP_MODE:?APP_MODE est obligatoire}

Remplacez l’image par celle de votre projet. Le suffixe :? fait échouer la configuration si la valeur est absente ou vide ; retirez-le si une valeur vide est prévue.

Autre possibilité : fournir un fichier d’environnement au conteneur avec env_file :

services:
  app:
    image: mon-application:locale
    env_file:
      - ./app.env

app.env est ici lu pour le service app. Le .env utilisé pour l’interpolation et le fichier indiqué par env_file ont des rôles distincts, même si vous pouvez choisir le même fichier pour les deux. N’ajoutez pas de secrets à Git : utilisez le mécanisme de secrets adapté à votre déploiement.

Vérifier les priorités et recréer le conteneur

Une variable passée via environment prend le dessus sur la même variable issue de env_file. Une valeur présente dans votre shell peut aussi prendre le dessus sur .env lors de l’interpolation. Consultez la documentation de priorité pour les combinaisons plus complexes.

Après modification du fichier Compose ou de la valeur, recréez le service :

docker compose up -d --no-deps --force-recreate app

docker compose restart redémarre le conteneur existant et ne recharge pas ses variables. --no-deps évite de recréer les dépendances ; retirez-le si vous avez également modifié leur configuration.

Pour une valeur non sensible, confirmez sa présence :

docker compose exec app printenv APP_MODE

La commande suppose que printenv existe dans l’image. Pour un secret, vérifiez sa présence par un diagnostic applicatif qui n’en affiche pas la valeur. Si l’application ne le lit toujours pas, contrôlez le nom attendu par son code et son point de démarrage.

Ressources

• Docker — interpolation des variables Compose
• Docker — définir les variables d’un conteneur
• Docker — priorité des variables
• Docker Compose — guide complet