Docker-compose template variables vs environment variables

There is this reference on docker-compose environment variables.Due to the multiple ways in which we can define env variables, we are prone to mistaking what each of the options does.

Assume we have the below files

docker-compose.yml

services:
  web:
    image: some-image:1.0.0
    volumes:
      - ${DATA_PATH}:/data
    environment:
      - NODE_ENV=${NODE_ENV}
    restart: unless-stopped
    ports:
      - 10920:3000

.env

DATA_PATH=/home/data
NODE_ENV=development

Output

$ docker-compose config
services:
  web:
    environment:
      NODE_ENV: development
    image: some-image:1.0.0
    ports:
    - published: 10920
      target: 3000
    restart: unless-stopped
    volumes:
    - /home/data:/data:rw
version: '3.9'

You can pass a custom env file while running too as below

docker-compose --env-file dev.env up -d

So ideally speaking these are not environment variables but templating variables.The variables that you declare in your env file will be available in your docker-compose file for variable substitution as ${variable_name}.

These variables are not available in your container as environment variables.

For passing environment variables to your container you can use the below

web:
  env_file:
    - web-variables.env

or

web:
  environment:
    - NODE_ENV=production

So these will be available inside your container(i.e docker exec -it web printenv).So the flag(env-file or env_file) has different effects on how its used.

Oops! but the env file option from the command line injects the variables inside the container as env variables when you use docker itself

docker run --env-file=env_file_name alpine env

• Calling them as template variables instead of env variables if the purpose of some of these options is for compose file templating makes it more clear.
• .env files are generally used for maintaining application env variables.Now this combined with compose using .env as the default file for template variables makes it a bit confusing.
• --env-file cli flag has different behaviour between docker-compose vs docker.docker-compose treats them as template variables and docker injects them as env variables.Of course docker itself has no variable substitution.