Skip to content
Tutorials Center
My learning

Topics

Lesson 61 of 111 ยท Docker Compose

Environment, Variables and Secrets

Understand the two kinds of variables in Compose: interpolation in the file and environment inside containers. Covers .env, env_file, precedence, profiles, secrets and configs.

A Compose project almost always needs settings that change between machines: an image tag, a port, a database password, a log level. Hard-coding them in compose.yaml makes the file different on every laptop and unsafe to commit. Compose gives you several tools for this, and they are easy to mix up because they all involve "variables".

The key is to separate two different jobs. Interpolation fills in ${VARIABLES} while Compose reads the file. Container environment sets the variables your program sees at run time. They use different sources and different rules. Once that clicks, .env, env_file, environment, profiles, secrets and configs each have an obvious place. Every example below was run on Docker 29 with Compose v5.

Two jobs, two mechanisms

TEXT
 .env, shell variables ----> ${VAR} inside compose.yaml     (interpolation: the FILE)
 env_file, environment: ---> variables inside the container  (the PROCESS)

A value in .env does not automatically appear inside your containers. It only replaces ${...} placeholders in the Compose file. To put a value inside a container you must either reference it from environment: or list a file in env_file:. Beginners trip over this constantly, so we will prove it below.

Interpolation and the .env file

Compose automatically reads a file named .env that sits next to compose.yaml. Here is one:

INI
APP_TAG=3.19
APP_PORT=18091
GREETING=from dotenv

Reference these values with ${NAME}:

YAML
name: tcd-b9-env
services:
  show:
    image: alpine:${APP_TAG}
    environment:
      A: ${GREETING}
      B:
      C: literal
    command: ["sh", "-c", "echo \"A=$$A B=$$B C=$$C\""]
CONSOLE
$ docker compose up
show-1  | A=from dotenv B= C=literal

A took its value from .env through interpolation. B has no value in the file, which tells Compose "pass this variable through from my shell if it is set" (it is not, so it is empty). C is a plain literal. The shell wins over .env when both define a name:

CONSOLE
$ GREETING=shell B=passed docker compose up
show-1  | A=shell B=passed C=literal

You can also point at a different file with --env-file, which is a neat way to keep one file per environment:

CONSOLE
$ cat prod.env
GREETING=prod file
$ docker compose --env-file prod.env up
show-1  | A=prod file B= C=literal

Defaults and required values

Interpolation understands the same fallbacks as the shell:

Syntax Meaning
${VAR} Value of VAR, or empty if unset
${VAR:-default} default if VAR is unset or empty
${VAR-default} default only if VAR is unset
${VAR:?message} Stop with message if VAR is unset or empty

Combine them to write files that work out of the box but fail loudly when something important is missing:

YAML
services:
  show:
    image: alpine:${APP_TAG}
    env_file:
      - app.env
    environment:
      MODE: ${MODE:-dev}
      DB_URL: postgres://${DB_USER:-app}@db/${DB_NAME:?DB_NAME must be set}

Without DB_NAME, Compose refuses to continue, before any container is touched:

CONSOLE
$ docker compose config
error while interpolating services.show.environment.DB_URL: required variable DB_NAME is missing a value: DB_NAME must be set

With the value supplied, you can see exactly what Compose resolved by running docker compose config, which prints the final file with all variables replaced:

CONSOLE
$ DB_NAME=shop docker compose config
...
    environment:
      DB_URL: postgres://app@db/shop
      GREETING: from app.env
      LOG_LEVEL: debug
      MODE: dev
      QUOTED: two words
    image: alpine:3.19
...

MODE fell back to dev, DB_USER to app, and the image tag came from .env. docker compose config is your best debugging friend for anything involving variables; run it whenever a value surprises you. List the variables a file uses with docker compose config --variables.

A literal dollar sign in the file is written $$ (as in $$HOME). That is why the command above says $$A: Compose turns it into $A for the container's shell. See Services in Compose for the same trick in command.

env_file: whole files into the container

When a service needs many variables, list a file under env_file. Every KEY=value line becomes an environment variable inside the container:

INI
GREETING=from app.env
LOG_LEVEL=debug
# comment line
QUOTED="two words"
YAML
services:
  show:
    image: alpine:3
    env_file:
      - app.env
    command: ["sh", "-c", "env | grep -E '^(GREETING|LOG_LEVEL|QUOTED)=' | sort"]
CONSOLE
$ docker compose up
show-1  | GREETING=from app.env
show-1  | LOG_LEVEL=debug
show-1  | QUOTED=two words

Comments are skipped and surrounding quotes are removed. Notice that GREETING from app.env is not replaced by the GREETING in .env or in your shell: env_file content goes into the container as written. The file is only a source for the container, not for interpolation.

If a listed file does not exist, Compose stops with an error. Mark optional files with the long form:

YAML
    env_file:
      - path: missing.env
        required: false
      - path: app.env
CONSOLE
$ docker compose up
show-1  | debug

Precedence inside the container

When the same name is set in several places, the more specific wins. From strongest to weakest:

  1. docker compose run -e NAME=value on the command line
  2. environment: in the Compose file
  3. env_file: files (later files override earlier ones)
  4. ENV instructions in the image's Dockerfile

We can check the middle two:

YAML
services:
  show:
    image: alpine:3
    env_file: app.env
    environment:
      GREETING: from environment key
    command: ["sh", "-c", "echo $$GREETING"]
CONSOLE
$ docker compose up
show-1  | from environment key

app.env also defines GREETING, but the environment: key won. See Configuring Containers for the plain docker run equivalent and ENV and ARG for the image-level defaults.

Add .env and any file with real credentials to .gitignore, and commit a .env.example with fake values instead. Also add them to .dockerignore so they never end up in an image (see Build Context and .dockerignore).

Profiles: optional services

Some services are only useful sometimes: a debugging tool, a database seeder, an admin UI. Give them a profile and Compose skips them unless you ask:

YAML
services:
  app:
    image: alpine:3
    command: ["echo", "app ran"]
  tools:
    image: alpine:3
    command: ["echo", "tools ran"]
    profiles: ["debug"]
  seed:
    image: alpine:3
    command: ["echo", "seeded"]
    profiles: ["setup", "debug"]

A service with no profiles always starts. The others start only when one of their profiles is active:

CONSOLE
$ docker compose config --services
app
$ docker compose --profile debug config --services
app
seed
tools
$ COMPOSE_PROFILES=setup docker compose config --services
seed
app

Activate profiles with --profile NAME (repeatable), or with the COMPOSE_PROFILES environment variable (comma-separated). A service can sit in several profiles, like seed above. You can also run a profiled service directly by naming it: docker compose run --rm tools works without activating debug first. The more advanced uses (a dev profile versus a production profile) are in Multiple Files, Profiles and Extends.

Secrets

An environment variable is convenient but leaky: it shows up in docker inspect, in crash dumps, and in every child process. For passwords and tokens, Compose offers secrets: values delivered to the container as files, under /run/secrets/<name>.

YAML
name: tcd-b9-sec
services:
  app:
    image: alpine:3
    command: ["sh", "-c", "echo pw=$$(cat /run/secrets/db_password); ls -l /run/secrets; env | grep -c s3cret"]
    secrets:
      - db_password

secrets:
  db_password:
    file: ./db_password.txt
CONSOLE
$ docker compose up
app-1  | pw=s3cret-pw
app-1  | total 0
app-1  | -rwxrwxrwx    1 root     root            10 Oct 23 14:53 db_password
app-1  | 0

The program read the password from the file, and the final line shows env | grep -c s3cret found zero matches: the secret is in a file, not in the environment. Official images follow this convention through variables ending in _FILE, such as POSTGRES_PASSWORD_FILE=/run/secrets/db_password, so the image reads the file itself.

Two honest caveats. First, the file mode shown above (rwxrwxrwx) came from Docker Desktop; on a Linux engine the file is typically owned by root and not world-writable, and you can set uid, gid and mode in the long syntax. Second, Compose secrets from file: are still just a bind-mounted file: they protect against leaking through the environment, not against someone with access to the host. Real secret stores and rotation belong to Managing Secrets.

Configs

configs look almost identical to secrets but are for non-sensitive configuration files that you want to mount at a specific path, such as an nginx or application config:

YAML
services:
  app:
    image: alpine:3
    command: ["cat", "/etc/app.conf"]
    configs:
      - source: appconf
        target: /etc/app.conf

configs:
  appconf:
    file: ./app.conf
CONSOLE
$ docker compose up
app-1  | server_name demo;
app-1  | level=info

For a single local file, a bind mount (./app.conf:/etc/app.conf:ro) does the same job and is more common in development. configs become attractive when the same file definition is shared by several services or must work unchanged on Swarm (Docker Swarm Basics).

Which one should I use?

Need Use
Image tag, host port, anything in the file that varies ${VAR} with .env
Many plain settings for one service env_file
A few settings, or overrides environment
Passwords, tokens, keys secrets (or a secret manager)
A config file at an exact path configs or a read-only bind mount
Services only some of the time profiles

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. .env contains LOG_LEVEL=debug, but compose.yaml never mentions LOG_LEVEL. What will a container see?

    .env is used when Compose reads the file. A variable reaches a container only through environment: or env_file:.
  2. 2. What does ${DB_NAME:?DB_NAME must be set} do when DB_NAME is not set?

    The :? form makes a variable required. Compose fails during interpolation and prints your message, before creating anything.
  3. 3. The same variable is set in env_file and in environment:. Which value does the container get?

    environment: has higher precedence than env_file, so it overrides the file.
  4. 4. Why prefer Compose secrets over environment: for a database password?

    A file-based secret stays out of docker inspect output and child-process environments. It is not magic encryption, but it removes common leaks.
  5. 5. A service has profiles: ["debug"]. When does docker compose up start it?

    Services with profiles are skipped unless one of their profiles is active (via --profile or COMPOSE_PROFILES) or you target the service by name.

Summary

  • Interpolation (${VAR} in the file) and container environment (environment, env_file) are separate mechanisms.
  • Compose reads .env automatically; the shell overrides it, and --env-file swaps it.
  • Use ${VAR:-default} for fallbacks and ${VAR:?message} for required values; inspect the result with docker compose config.
  • environment beats env_file; mark optional files with required: false.
  • profiles keep optional services out of normal up runs.
  • secrets mount values as files in /run/secrets; configs mount non-sensitive files at a chosen path.
  • Keep real credentials out of Git and out of images.

Next: Startup Order and Health