Compose Expands Variables Before Starting the Container

A voice application may use one language during local testing and another in a deployed container, even though both runs use the same compose.yaml. The first place to inspect is the rendered Compose configuration. Compose substitutes variables while it reads the file, before it creates the container. The resulting service definition determines what Docker starts.

Consider this illustrative service:

services:
  voice:
    image: example/voice:${IMAGE_TAG:-stable}
    environment:
      LANGUAGE: ${LANGUAGE:-en}
    command: ["sh", "-c", "exec voice-server --lang \"$${LANGUAGE}\""]

If IMAGE_TAG is absent, Compose selects stable. If LANGUAGE is absent or empty, it selects en. The colon matters: ${LANGUAGE-en} would use en only when the variable is unset, preserving an explicitly empty value. These forms are specified in Docker’s interpolation guide. Use ${LANGUAGE:?Set LANGUAGE} when an empty language would be a deployment error rather than a useful default.

Compose takes interpolation inputs from the shell environment, then from an explicit --env-file, or from its default .env lookup. A value in .env is available to Compose for substitution; it does not automatically become a process variable. Here, LANGUAGE reaches the voice process because the service declares it under environment. IMAGE_TAG only selects an image. This distinction matters when a model downloader or speech worker expects a setting inside the container: adding a value to .env alone may leave that process unaware of it.

The command contains $${LANGUAGE} for a different reason. The doubled dollar sign tells Compose to leave a literal dollar sign for the container’s shell. The shell then expands ${LANGUAGE} after startup, using the container environment. The Compose specification documents this escape. It only postpones expansion; it does not supply the variable. If the image invokes a program directly rather than a shell, a literal $LANGUAGE argument remains literal unless that program interprets it.

Before starting a voice stack, run docker compose config --environment to inspect interpolation inputs, then docker compose config to inspect the resolved service. Treat real output as sensitive if it contains credentials. Decide separately which values choose the Compose model and which ones the application must receive at runtime, and declare the latter in the service configuration.