Docker Compose Variable Interpolation#

Docker Compose supports Bash-like variable substitution in Compose files using $VARIABLE or ${VARIABLE} syntax. When a variable cannot be resolved and no default is provided, Compose does not error — it silently substitutes an empty string and emits a warning 1. This silent fallback is the root cause of several common security and runtime bugs in course exercises.

Interpolation Syntax#

The Compose Specification supports four substitution forms for braced expressions:

Interpolation applies to YAML values only, not to keys. For label/environment keys, use the list (- KEY=VALUE) form rather than the map form 1. Use $$ to escape a literal dollar sign and prevent interpolation 1.

Variable sources are resolved in this precedence order 2:

1. Shell environment
2. File specified by --env-file
3. .env file in the project directory

The Silent Empty-String Trap#

If POSTGRES_VERSION is unset and you write image: "postgres:${POSTGRES_VERSION}", Compose resolves this to image: "postgres:" — an invalid image reference. Docker's own docs flag this as a likely error: postgres: is not a valid tag 2.

The same silent substitution applies to any field — including the user: directive that controls which OS user runs processes inside the container.

Security Risk: CURRENT_UID and Running as Root#

The course docker-compose.yml uses ${CURRENT_UID} to set the container process owner 3 4:

user: ${CURRENT_UID}

The .env file ships with:

CURRENT_UID=0 # Root by default

This means:

• If a student runs docker compose up without overriding CURRENT_UID, the container runs as UID 0 (root), defeating the security intent of the user: directive.
• If CURRENT_UID is entirely unset (no .env, no shell export), Compose substitutes an empty string, which Docker interprets as the image's default user — often also root.

The course slides document this explicitly: the user: field is set to ${CURRENT_UID} so that files written to mounted volumes are owned by the host user rather than root. If the variable is missing, containers silently run as root 5.

Mitigations#

Use ${VAR:?error} for required variables. This causes docker compose config and docker compose up to fail fast with a descriptive message if the variable is unset or empty — instead of silently proceeding with a broken or insecure value 1.

Set CURRENT_UID explicitly before running Compose:

export CURRENT_UID=$(id -u)
docker compose up

Verify resolved values before starting containers:

docker compose config # Shows fully-resolved Compose file
docker compose config --environment # Shows all variables and their sources

Key References#

• Compose Specification: Interpolation — syntax reference and substitution rules
• How-to: Variable Interpolation — .env file format, precedence, and examples
• Course docker-compose.yml — anchor block showing user: ${CURRENT_UID} pattern
• .env defaults — CURRENT_UID=0 shipped as the default
• Course slides on user: and CURRENT_UID — explanation of the security intent and failure mode