Developer tools · Docker run to Docker compose converter
Environment variables in Compose: -e, --env-file and interpolation
· How it works
docker compose environment-variables
There are three places a variable can come from in Compose, and they behave differently. This post maps -e and --env-file to their keys and explains what Compose interpolates and when.
The app connected with the password ${DB_PASSWORD}, literally — after a hand-written Compose file replaced a working docker run
The app connected with the password ${DB_PASSWORD}, literally — after a hand-written Compose file replaced a working docker run. Evidence: an environment expression remains literal when supplied literally. Reproduce environment sourcing with disposable literals. Pair each source occurrence with environment and env_file; reserve literal values and file boundaries for destination review.
The environment variables incident also reveals that A separate environment variables incident boundary is that the tokeniser never resolves dollar interpolation or defaults. Evidence: the tokeniser never resolves dollar interpolation or defaults. This environment sourcing constraint is a stopping point. Inspect environment and env_file without manufacturing behavior, then document a host check for literal values and file boundaries.
-e KEY=value becomes environment: — as a list or a map, and the KEY-only form that passes through a host variable
-e KEY=value becomes environment: — as a list or a map, and the KEY-only form that passes through a host variable. Evidence: -e values form an ordered environment sequence and KEY-only values trigger a note. Trace environment sourcing tokens into environment and env_file. Separate ordered values from last-value fields; literal values and file boundaries is outside collection.
A related environment variables mechanism boundary is that A separate environment variables grammar boundary is that spaces and additional equals signs survive quoted values. Evidence: spaces and additional equals signs survive quoted values. Use this environment sourcing fact to predict one member or scalar in environment and env_file. Check warnings before deciding anything about literal values and file boundaries.
--env-file becomes env_file: — a file the container reads, distinct from the .env file Compose itself reads
--env-file becomes env_file: — a file the container reads, distinct from the .env file Compose itself reads. Evidence: --env-file values form env_file entries and no referenced file is opened. Judge environment sourcing serialization from its model. Quoting in environment and env_file protects types but gives no operational proof for literal values and file boundaries.
The second environment variables serialization observation is A separate environment variables output boundary is that the browser returns YAML but does not execute docker compose config. Evidence: the browser returns YAML but does not execute docker compose config. This environment sourcing output separates settings from unavailable context. Keep environment and env_file reviewable and check literal values and file boundaries independently.
Interpolation is not performed by the converter; dollar expressions remain literal output text
Interpolation happens in the Compose file — ${VAR} and ${VAR:-default} are resolved by Compose before the container sees anything. Evidence: the tokeniser never resolves dollar interpolation or defaults; Interpolation is not performed by the converter; dollar expressions remain literal output text. Stop at the environment sourcing exception instead of guessing. Any addition near environment and env_file needs a deployment-specific reason tied to literal values and file boundaries.
Another environment variables exception constraint is that for this environment variables section keep the original for this environment variables section command and warnings for this environment variables section beside this candidate file. Evidence: the repository gives no broader runtime or historical proof. Keep the original environment sourcing command beside warnings. The comparison shows what environment and env_file contains and which literal values and file boundaries decision remains manual.
Worked example: -e POSTGRES_PASSWORD=secret -e TZ --env-file app.env — the YAML, and where each value ends up at runtime
Worked example: -e POSTGRES_PASSWORD=secret -e TZ --env-file app.env — the YAML, and where each value ends up at runtime. Build the environment sourcing example from synthetic names. Make every environment and env_file item traceable without exposing production literal values and file boundaries details.
The same environment variables example sample demonstrates that A separate environment variables example boundary is that separate environment and env_file lists reveal each command source. Evidence: separate environment and env_file lists reveal each command source. The paired environment sourcing fact should be visible in environment and env_file. Record that line and avoid assumptions about literal values and file boundaries.
The generated text can be inspected locally, but Docker must perform any Compose resolution
Checking the result — docker compose config prints the fully resolved file so you can see what the container will receive. Evidence: the browser returns YAML but does not execute docker compose config; The generated text can be inspected locally, but Docker must perform any Compose resolution. Translate the environment sourcing consequence into one observable environment and env_file difference. Docker owns the later literal values and file boundaries verdict.
The environment variables consequence implementation also shows for this environment variables section keep the original for this environment variables section command and warnings beside for this environment variables section this candidate file that environment variables consequence fact defines what for this environment variables section the browser contributed for this environment variables section docker still owns the environment variables consequence runtime verdict the for this environment variables section operator still owns the environment variables consequence security policy the for this environment variables section repository still needs the environment variables consequence secret removed keep for this environment variables section those responsibilities separate when for this environment variables section describing the generated service. Split environment sourcing responsibilities: conversion writes environment and env_file, the repository removes secrets, and operators validate literal values and file boundaries.
What this does not cover — Docker secrets, quoting rules inside env files, and variables set by the image's own Dockerfile
What this does not cover — Docker secrets, quoting rules inside env files, and variables set by the image's own Dockerfile. Evidence: secrets sections and image-defined defaults are outside the model. Limit environment sourcing scope to environment and env_file branches shown here. Neighboring forms and defaults cannot answer literal values and file boundaries questions.
One more environment variables scope limit follows from A separate environment variables limit boundary is that -e values form an ordered environment sequence and KEY-only values trigger a note. Treat this environment sourcing boundary as an exclusion. Prefer accurate environment and env_file over guesses about literal values and file boundaries.
Takeaway: know which file each variable comes from — and the converter shows -e and --env-file landing under the right keys
Takeaway: know which file each variable comes from — and the converter shows -e and --env-file landing under the right keys. Audit environment sourcing as source option, model field, environment and env_file line and warning. Remove secrets before checking literal values and file boundaries.
Finally, the environment variables takeaway source confirms A separate environment variables decision boundary is that --env-file values form env_file entries and no referenced file is opened. Close environment sourcing narrowly: environment and env_file is a candidate; literal values and file boundaries and shell equivalence are not guarantees.