Docker Compose Environment Files
Real applications need settings such as database passwords, port numbers, and feature switches. Writing those values directly inside the Compose file creates a mess. Environment files keep settings in a separate place, and the same Compose file then works on a laptop, a test server, and a production machine.
Why Separate Settings From the Compose File
Think of a Compose file as a recipe and an environment file as the shopping list for one specific dinner. The recipe stays the same, and the ingredients change with the guests.
docker-compose.yml (recipe: shared by everyone)
+
.env (values for this machine)
=
Running application
The Default .env File
Compose automatically reads a file named .env in the project folder. The file holds simple KEY=value lines.
# .env POSTGRES_USER=appuser POSTGRES_PASSWORD=change-me-please APP_PORT=8080 IMAGE_TAG=1.4
Compose replaces matching variables inside the YAML file before it starts anything.
services:
web:
image: my-web:${IMAGE_TAG}
ports:
- "${APP_PORT}:80"
db:
image: postgres:16
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
Default Values
Variable substitution supports fallback values for missing settings.
${APP_PORT:-3000} use 3000 when APP_PORT is empty or missing
${DB_HOST:?required} stop with an error when DB_HOST is missing
The second form protects you from silent mistakes. Compose refuses to start and prints the message you wrote.
The env_file Option
Substitution fills values inside the YAML file. The env_file option does something different. It passes every line of a file into the container as environment variables.
services:
api:
image: my-api
env_file:
- ./config/api.env
- ./config/shared.env
Later files override earlier files when both define the same key. This rule lets you place general defaults first and specific overrides last.
Two Different Jobs
.env file (project root) env_file option
------------------------ -----------------------------
Fills ${VARIABLES} in the Sends variables into the
Compose file itself running container
Many beginners expect the root .env file to appear inside containers automatically. It does not. Reference the variables in the environment section or use env_file to send them in.
Choosing a Different File
The --env-file flag picks another file for substitution.
docker compose --env-file .env.production up -d docker compose --env-file .env.staging up -d
Teams keep one file per environment and switch between them with one flag.
Order of Priority
Docker Compose resolves a variable from several places. The list below runs from strongest to weakest.
- A value passed with the docker compose run -e flag
- A variable set in your shell session
- A value in the environment section of the Compose file
- A value from an env_file
- A default set with the dash syntax
Shell variables beat file values. A quick override from the terminal works without editing any file.
Checking the Final Result
docker compose config
This command prints the Compose file after all substitution. Read the output to confirm every variable received the right value before you start the stack.
Protecting Sensitive Files
- Add .env to .gitignore so passwords never reach a public repository.
- Commit a file named .env.example with fake values to document the required keys.
- Keep production secrets in a dedicated secret manager when possible.
.env.example (safe to share) POSTGRES_USER=appuser POSTGRES_PASSWORD= APP_PORT=8080
New team members copy the example file, fill in their own values, and start the project in minutes.
Real-World Scenario
A team of four developers shares one Compose file for an online store project. Each developer uses a different local port, because other programs already occupy port 8080 on two laptops. The team puts APP_PORT in each person's private .env file. The Compose file stays identical for everyone, and Git never shows a conflict over port numbers.
The same project deploys to a staging server and a production server. The staging file points to a test database, and the production file points to the real one. The deployment script passes --env-file .env.production, and no one edits the shared YAML.
Checking for Missing Values
A blank variable causes confusing errors, such as a database that rejects an empty password. Compose prints a warning when a referenced variable has no value. Treat that warning seriously and fix the missing line before you start the stack. The required syntax with a question mark turns the warning into a hard stop for settings that must never stay empty.
