Environment, .env, and Interpolation

There are two different "environments" in Compose, and conflating them is the usual source of confusion. One is the environment inside the container — what your app reads via os.environ — set with environment: or env_file:. The other is variable interpolation in the compose file itself — ${TAG} or ${POSTGRES_PASSWORD} substituted as Compose parses the YAML, fed automatically from a .env file in the project directory.

They look similar — both are KEY=value — and they live in completely different worlds. One reaches a running container; the other only shapes the file Compose reads. Keeping the two destinations straight is most of what this topic is about.

environment: — Inline Container Env

A list or map under a service's environment: key sets environment variables in that container. Driftwood's web gets DATABASE_URL and SECRET_KEY this way, and db gets POSTGRES_PASSWORD. The values are baked into the parsed configuration and end up in the container's process environment, where the application reads them at runtime — and they show up in docker compose config, which prints the fully resolved file.

env_file: — Container Env From a File

env_file: points a service at a file of KEY=value lines that Compose loads into that container's environment. It is the same destination as environment: — the container — but sourced from a file, which is handy when a service needs many variables. The crucial thing is the name: this is distinct from the .env interpolation file, despite the near-identical look, because env_file: feeds a container and .env feeds the parser.

The .env File and Interpolation

A .env file sitting next to compose.yaml is auto-loaded by Compose to resolve ${VAR} references in the compose file — image tags, ports, paths. This substitution happens at parse time, before any container exists, and it does not by itself put anything inside a container. If .env contains TAG=1.4.0 and the file says image: driftwood/web:${TAG}, Compose reads the file as driftwood/web:1.4.0. The container never sees TAG unless an environment: entry also references it.

# .env — auto-loaded for ${VAR} interpolation
TAG=1.4.0
POSTGRES_PASSWORD=secret

# compose.yaml — ${...} resolved at parse time
services:
  web:
    image: driftwood/web:${TAG}
    environment:
      DATABASE_URL: postgres://driftwood:${POSTGRES_PASSWORD}@db:5432/driftwood
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

${TAG} only shapes which image tag web runs — it never reaches a container. ${POSTGRES_PASSWORD} reaches the containers only because each service's environment: explicitly references it; the .env entry alone would not have. That double step — interpolate into the file, then the file's environment: carries it into the container — is the bridge between the two worlds.

Precedence and Resolution Order

When the same name appears in more than one place, a fixed precedence decides which value wins, and getting it wrong means the value you set silently does not take effect. For interpolation, a value already exported in the shell environment beats the .env file — so TAG=2.0.0 docker compose up overrides .env's TAG. For container environment, an explicit environment: entry beats anything in env_file:. Knowing the order matters most when a stale shell export quietly overrides the .env you just edited.

The Secret-in-.env Footgun

Driftwood's naive Layer-A approach puts POSTGRES_PASSWORD and SECRET_KEY in .env. It is convenient, and that convenience is exactly why secrets leak. .env sits in the project directory, so it is one stray git add . away from the repository — and docker compose config prints every resolved value in plaintext, so a routine debugging command in a shared terminal or CI log dumps the password.

Add .env to .gitignore from the first commit and treat the secret-in-.env pattern as the throwaway Layer-A shortcut it is. The real fix — database passwords and SECRET_KEY delivered as files through Docker and Compose secrets — is Layer B's job in Chapter 10, and it removes the plaintext from both the repo and the config output.