Docker Compose env_file, environment en .env: wat doet wat
Gids voor Docker Compose env_file
Docker Compose env_file vs environment vs .env uitgelegd | We.Inc
Wat env_file, environment en het .env-bestand elk doen in Docker Compose, welke waarde wint als ze botsen en hoe interpolatie met ${VAR:-default} werkt, met een resolver.
In Docker Compose laadt env_file een bestand met KEY=value-regels in de container van één service. Het attribuut environment zet containervariabelen inline en wint van env_file als beide dezelfde key noemen. Het .env-bestand naast compose.yaml is iets anders: Compose leest het om ${VAR}-placeholders in de YAML zelf in te vullen.
Drie manieren om variabelen aan Compose te geven
Mechanisme
Bereik
Komt het in de container?
.env naast compose.yaml
Interpolatie van ${VAR} in het Compose-bestand
Alleen als een service ernaar verwijst
env_file: op een service
De container van die service
Ja, elke regel
environment: op een service
De container van die service
Ja, en het wint van env_file
--env-file op de CLI
Vervangt de standaard-.env voor interpolatie
Alleen als ernaar verwezen wordt
De verwarring komt door de naam: een bestand dat .env heet en een attribuut dat env_file heet klinken hetzelfde, maar het ene configureert het Compose-bestand en het andere een container. Gebruik de resolver om te zien welke bron wint voor een variabele, en probeer daarna de interpolatievormen uit met een gezette, lege of niet-gezette variabele.
Vink elke plek aan waar uw variabele gezet is en typ de waarde die hij daar heeft.
De resolver loopt de gedocumenteerde voorrangslijst van Docker van boven af door en toont welke waarde de container uiteindelijk krijgt.
Kies in het interpolatievak een vorm zoals ${VAR:-default}, kies of VAR gezet, leeg of niet gezet is, en lees het resultaat.
Draai docker compose config in uw project om te bevestigen wat Compose werkelijk heeft opgelost.
Draai docker compose config --environment om de variabelen te tonen die Compose voor interpolatie gebruikte. Dat beslecht de meeste discussies in seconden.
Markeer optionele env-bestanden met required: false (Compose 2.24.0 en later), zodat een ontbrekende lokale override de stack niet stopt.
Schrijf $$ als u een letterlijk dollarteken nodig hebt in compose.yaml, bijvoorbeeld in een wachtwoord of een shellcommando.
Zet booleans in de environment-map tussen aanhalingstekens, zoals SHOW: "true", zodat YAML er geen true- en false-waarden van maakt.
Veelgestelde vragen
Wat is het verschil tussen env_file en environment?
Beide zetten variabelen in de container van een service. env_file leest ze uit een of meer bestanden, environment somt ze op in compose.yaml. Staat dezelfde key in beide, dan wint de waarde uit environment, ook als die leeg is.
Geeft Compose mijn .env-bestand automatisch door aan containers?
Nee. Het .env-bestand van het project wordt alleen gebruikt om ${VAR} in het Compose-bestand te vervangen. Een variabele komt pas in een container als een service hem onder environment noemt, of het bestand laadt met env_file.
Waar zoekt Compose naar het .env-bestand?
In de projectmap: de map die met --project-directory is opgegeven, anders de map van het eerste -f-bestand, anders uw huidige map. Gebruik --env-file om naar een ander bestand te wijzen; bij meerdere bestanden overschrijven latere de eerdere.
Zijn env_file-paden relatief aan de plek waar ik het commando draai?
Nee. Relatieve paden in env_file worden opgelost vanaf de map waarin het Compose-bestand staat, dus de stack werkt ongeacht waar u hem start.
Wat gebeurt er met ${VAR} als VAR niet gezet is?
Compose toont een waarschuwing en vult een lege string in. Gebruik ${VAR:-fallback} om een standaardwaarde te geven, of ${VAR:?message} om in plaats daarvan met een foutmelding te stoppen.
De voorrangslijst, van boven naar beneden
Docker documenteert vijf niveaus. Een waarde die met docker compose run -e wordt meegegeven is het sterkst. Daarna komt environment of env_file waarbij de waarde wordt geïnterpoleerd uit uw shell of een omgevingsbestand, dan een letterlijke waarde onder environment, dan een waarde uit env_file, en als laatste een ENV-regel die in de image is ingebakken.
Merk op dat slechts één hiervan het .env-bestand is, en dan nog indirect: het voedt niveau twee via interpolatie. Een waarde in .env die geen enkele service noemt, verschijnt nooit in een container.
Keys zonder waarden
Een kale naam onder environment, zoals - API_TOKEN zonder isgelijkteken, kopieert de waarde uit de shell waarin Compose draait. Heeft de shell hem niet, dan blijft de variabele niet gezet.
In een env_file maakt een regel met alleen een key die variabele leeg en verwijdert hem uit de containeromgeving, wat handig is om bewust iets te wissen dat de image zet.
Alle interpolatievormen
Wat elke vorm oplevert bij een gezette, lege of niet-gezette VAR
Vorm
VAR=abc
VAR leeg
VAR niet gezet
${VAR} or $VAR
leeg, met een waarschuwing
${VAR:-default}
${VAR-default}
${VAR:?msg}
fout msg
fout msg
${VAR?msg}
fout msg
${VAR:+other}
${VAR+other}
een letterlijke $
een letterlijke $
een letterlijke $
Compose-bestanden om te kopiëren
env_file plus overrides met environment
Gedeelde instellingen komen uit bestanden; de environment-regels winnen voor de keys die ze noemen. Het lokale bestand is optioneel.
Project-.env alleen gebruikt voor interpolatie
Deze twee waarden vullen placeholders in compose.yaml. Geen van beide komt in een container, tenzij een service ernaar verwijst.
Die waarden gebruiken in compose.yaml
De image-tag en de gepubliceerde poort komen uit .env; het wachtwoord moet gezet zijn, anders stopt Compose met een duidelijke melding.
Controleer wat Compose heeft opgelost
config toont het uiteindelijke model met elke variabele ingevuld; --environment somt de waarden op die voor vervanging zijn gebruikt.
Welke waarde wint?
De variabele APP_MODE is gezet op de plekken die hieronder zijn aangevinkt.
Waar de variabele gezet is
Waarde
De container krijgt APP_MODE={v} van: {n}
Nergens gezet, dus APP_MODE ontbreekt in de container.
Interpolatietester
Expressie
VAR is
gezet maar leeg
Waarde van VAR
Resultaat: {v}
Resultaat: een lege string
Compose stopt met de foutmelding: {v}
Resultaat: een lege string, en Compose toont een waarschuwing