Skip to content

Docker Compose and environment variables

Docker Compose describes an application made of several containers (an API, a database, a cache) in one YAML file and runs it with one command. It is the standard way to run a realistic stack on a developer machine or in CI, and a reasonable way to run small single-host deployments. Because configuration is where most Compose problems come from, this page also covers environment variables in depth: for plain docker run, in Dockerfiles, and in Compose, including interpolation, precedence and secrets.

The examples use the invented OrdersPortal stack: an ASP.NET Core api, PostgreSQL 18 and Redis. Every Compose file on this page was validated with docker compose config using Docker Compose 5.6; outputs shown from that command were produced in that run. Commands that start containers need a Docker daemon, which was not available, so they are not run here.

Topic What it answers
What Compose is What Compose manages and where it fits.
A complete compose file Services, builds, ports, volumes, networks and secrets for one stack.
Everyday commands Starting, stopping, logs, exec and one-off commands.
Startup order and health checks Making the API wait until the database is actually ready.
Compose files and overrides Development versus production settings, profiles and file watch.
Environment variables -e, --env-file, ENV versus ARG, and Compose’s environment and env_file.
Interpolation and precedence ${VAR} substitution, the .env file, and which value wins.
Secrets Keeping passwords out of environment variables and images.

Compose turns a YAML file into Docker objects: one or more containers per service, a network for the project, named volumes, and secrets and configs mounted into containers. It reconciles what is running with the file, so running docker compose up again after an edit recreates only the services whose configuration changed. Everything Compose creates is labeled with the project name (by default the directory name, or the top-level name:), so several projects can run side by side.

The file format is the Compose Specification. The default file name is compose.yaml (docker-compose.yml is still recognized). The top-level version: field is obsolete: it is ignored and Compose prints a warning if you include it. The command is docker compose (a Docker CLI plugin, version 5.x in 2026); the old standalone docker-compose Python tool is retired.

Compose runs on one Docker host. For several hosts, failover and autoscaling, use an orchestrator such as Kubernetes; the concepts (services, networks, volumes, configuration) carry over.

Pitfalls:

  • Copying tutorials that start with version: '3.8'. Harmless but obsolete; remove it.
  • Treating Compose as a cluster. A restart policy restarts crashed containers, but nothing moves them if the host fails.
compose.yaml
name: ordersportal
services:
api:
build:
context: .
target: runtime
image: registry.example.test/ordersportal/orders-api:${ORDERS_API_TAG:-dev}
ports:
- "127.0.0.1:8080:8080"
environment:
ASPNETCORE_ENVIRONMENT: Development
ConnectionStrings__Orders: Host=db;Database=orders;Username=orders_app
Redis__Host: cache
env_file:
- path: ./api.local.env
required: false
secrets:
- db_password
depends_on:
db:
condition: service_healthy
cache:
condition: service_started
networks: [frontend, backend]
db:
image: postgres:18-alpine
environment:
POSTGRES_DB: orders
POSTGRES_USER: orders_app
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
volumes:
- orders-data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U orders_app -d orders"]
interval: 5s
timeout: 3s
retries: 10
networks: [backend]
cache:
image: redis:8-alpine
networks: [backend]
volumes:
orders-data:
networks:
frontend:
backend:
internal: true
secrets:
db_password:
file: ./secrets/db_password.txt

Each service either builds an image (build, here the runtime stage of the multi-stage Dockerfile) or pulls one (image); with both, the built image gets that name. Services reach each other by service name on shared networks (Host=db, Redis__Host: cache), the database and cache sit on an internal network with no outside access, and only the API publishes a port, on loopback. The PostgreSQL 18 volume is mounted at /var/lib/postgresql, the image’s data location since version 18 (see volumes). ASP.NET Core reads ConnectionStrings__Orders as the configuration key ConnectionStrings:Orders, because a double underscore stands for the section separator in environment variable names.

Pitfalls:

  • Publishing every service’s port “for debugging”. Use docker compose exec or a temporary port mapping instead, and keep data stores unpublished.
  • Hard-coding passwords in the file. The file is committed. Use secrets or an untracked env file.
Terminal window
# Not run here: these start containers and need a Docker daemon
docker compose up -d # build if needed, create and start everything in the background
docker compose up -d --build api # rebuild and recreate one service
docker compose ps # status and health of the project's containers
docker compose logs -f api # follow one service's logs
docker compose exec api sh # shell in a running container
docker compose run --rm api dotnet ef database update # one-off command in a new container
docker compose restart api
docker compose stop # stop, keep containers
docker compose down # stop and remove containers and networks; keep volumes
docker compose down -v # also delete named volumes (data)
docker compose config # validate and print the fully resolved file

docker compose config is the most underused of these. It merges all files, resolves variables and prints the result, so it answers “what will actually run?” without starting anything; CI can run it to validate Compose files.

Pitfalls:

  • up without --build after changing the Dockerfile. Compose reuses the existing image. Add --build, or use file watch in development.
  • run versus exec. run starts a new container (with the service’s configuration), exec enters an existing one.

depends_on controls start order, but a plain list (depends_on: [db]) only waits until the database container has started, not until PostgreSQL accepts connections. The long form with condition: service_healthy waits until the dependency’s health check passes, which is why the sample gives db a pg_isready health check. service_started (the default) and service_completed_successfully (for one-off setup containers such as migrations) are the other conditions.

Health checks are also visible in docker compose ps, so they help debugging beyond startup. Applications should still retry connections: in production, dependencies restart independently of your service, and no startup ordering helps then.

Pitfalls:

  • Using sleep 10 in an entrypoint to wait for the database. It is too long on fast machines and too short on slow CI runners. Use a health check condition.
  • A health check that needs a tool missing from the image. curl is not in many slim images; use a tool the image has, or a small built-in health endpoint client.

Compose merges several files, which keeps one base file and small environment-specific differences. By default it reads compose.yaml and, if present, compose.override.yaml, so the override file is the natural home for development-only settings:

# compose.override.yaml - picked up automatically in development
services:
api:
build:
target: build # SDK stage for hot reload
command: ["dotnet", "watch", "run", "--project", "src/Orders.Api"]
develop:
watch:
- action: sync
path: ./src
target: /src/src

For other environments, name the files explicitly; later files override earlier ones:

compose.prod.yaml
services:
api:
restart: unless-stopped
environment:
ASPNETCORE_ENVIRONMENT: Production
Terminal window
ORDERS_API_TAG=2.4.1 docker compose -f compose.yaml -f compose.prod.yaml config
api:
restart: unless-stopped
environment:
ASPNETCORE_ENVIRONMENT: Production
ConnectionStrings__Orders: Host=db;Database=orders;Username=orders_app
Redis__Host: cache
image: registry.example.test/ordersportal/orders-api:2.4.1

Maps such as environment merge key by key, while single values such as command are replaced. Profiles mark optional services (for example an admin UI or a load generator) that start only with docker compose --profile tools up. File watch (docker compose watch, or up --watch) syncs changed source files into the running container or rebuilds the image, which avoids slow bind mounts on Docker Desktop.

Pitfalls:

  • Forgetting the override is automatic. A production server with a stray compose.override.yaml runs development settings. Use explicit -f files outside development.
  • Divergent copies instead of overrides. Two full compose files drift apart; keep one base file.

Configuration that differs between environments (URLs, feature flags, log levels) should be passed to containers at run time, not baked into images. There are several ways to set a container’s environment.

With plain docker run, use -e NAME=value for single values and --env-file for a file of NAME=value lines. -e NAME without a value passes through the value of NAME from your shell.

Terminal window
# Not run here
docker run -e ASPNETCORE_ENVIRONMENT=Staging --env-file ./api.staging.env \
registry.example.test/ordersportal/orders-api:2.4.1

In a Dockerfile, ENV sets a default that exists at build time and in every container, and run-time settings override it. ARG exists only during the build. To give a build value to the running application, copy it: ARG APP_VERSION then ENV APP_VERSION=$APP_VERSION. Never pass secrets through either; both end up visible in the image metadata or history.

In Compose, the environment attribute sets variables directly, and env_file loads them from files. Both can be combined, and env_file entries can be marked required: false so a developer-specific file is optional, as in the sample’s api.local.env. Commit an example file with placeholder values (api.local.env.example) and keep the real one out of Git.

Applications should validate configuration at startup and fail fast with a clear message when a required value is missing, rather than failing on the first request.

Pitfalls:

  • Committing .env files with real credentials. Add them to .gitignore and to .dockerignore.
  • Expecting changed variables to apply to a running container. Environment is fixed at container creation; recreate the container (docker compose up -d does this when configuration changed).

Compose uses environment variables in two different ways, and confusing them causes most surprises.

Interpolation substitutes ${VAR} placeholders in the Compose file itself, before anything runs, using your shell environment and a .env file in the project directory. ${VAR:-default} supplies a default, and ${VAR:?message} makes Compose fail with a message when the variable is missing. Container environment is what the process inside the container sees, set by environment and env_file. The .env file feeds interpolation; it is not automatically injected into containers.

This file uses both:

compose.yaml
services:
api:
image: registry.example.test/ordersportal/orders-api:${ORDERS_API_TAG:-dev}
env_file: api.env
environment:
LOG_LEVEL: Information
PAYMENTS_URL: ${PAYMENTS_URL:?PAYMENTS_URL must be set}
.env
ORDERS_API_TAG=2.4.0
# api.env
LOG_LEVEL=Debug
FEATURE_GUEST_CHECKOUT=false

Without PAYMENTS_URL in the shell, validation fails early:

$ docker compose config
error while interpolating services.api.environment.PAYMENTS_URL: required variable PAYMENTS_URL is missing a value: PAYMENTS_URL must be set

With it set, the resolved service shows both mechanisms at work:

$ PAYMENTS_URL=https://payments.example.test docker compose config
api:
environment:
FEATURE_GUEST_CHECKOUT: "false"
LOG_LEVEL: Information
PAYMENTS_URL: https://payments.example.test
image: registry.example.test/ordersportal/orders-api:2.4.0

LOG_LEVEL from environment beat the value in api.env, and the image tag came from .env. Running the same command with ORDERS_API_TAG=2.4.1 exported in the shell produced orders-api:2.4.1: for interpolation, the shell overrides .env.

For the container’s environment, Docker’s documentation gives this order, highest first:

  1. docker compose run -e on the command line.
  2. environment or env_file entries whose value is interpolated from the shell or an environment file.
  3. Values set directly in environment.
  4. Values from env_file.
  5. ENV in the image’s Dockerfile.

Pitfalls:

  • Expecting .env values inside the container. Reference them explicitly (LOG_LEVEL: ${LOG_LEVEL}) or use env_file.
  • A stray exported shell variable. An old export ORDERS_API_TAG=... silently overrides .env. Check with docker compose config.

Environment variables are convenient but leaky: they appear in docker inspect, in process listings inside the container, in crash dumps and sometimes in logs. Compose secrets mount sensitive values as files instead. A top-level secrets entry defines the source (a file, or an environment variable on the host with environment:), and each service that lists the secret gets it at /run/secrets/<name>.

In the sample, PostgreSQL reads its password from POSTGRES_PASSWORD_FILE=/run/secrets/db_password (many official images support this _FILE convention), and the API can read the same file at startup. docker compose config shows the mount target:

secrets:
- source: db_password
target: /run/secrets/db_password

Keep the secret file itself out of Git. In CI, write it from the pipeline’s secret store just before docker compose up. On Kubernetes the equivalent is a Secret mounted as a volume (see ConfigMaps and Secrets), and cloud platforms offer managed secret stores such as Azure Key Vault, AWS Secrets Manager and Google Secret Manager.

Pitfalls:

  • Passing secrets as build arguments. They are recorded in image history. Use build secrets.
  • Logging the whole configuration at startup. It prints the secrets you carefully mounted. Log keys, not values.
Need Use
Local full stack for development compose.yaml plus an automatic compose.override.yaml and file watch
Same stack with production settings on one host Base file plus -f compose.prod.yaml, pinned image tags
Optional tools Profiles
Wait for a dependency to be ready depends_on with condition: service_healthy
Non-secret per-environment settings environment or env_file
Values for the Compose file itself (tags, ports) Interpolation from the shell or .env
Passwords and keys Compose secrets mounted under /run/secrets

What is the difference between .env and env_file? .env in the project directory provides values for interpolating ${VAR} placeholders in the Compose file. env_file lists files whose variables are set in a container’s environment.

Why can the API still fail to connect even with depends_on: [db]? The short form waits only for the database container to start, not for the database to accept connections. Use a health check with condition: service_healthy, and retry connections in the application.

What is the difference between ARG and ENV? ARG is available only while building the image. ENV is set during the build and in every container from the image, and can be overridden at run time.

How do you see the configuration Compose will actually apply? Run docker compose config with the same files and environment; it merges files, resolves variables and prints the result without starting anything.

Senior scenario: OrdersPortal runs on two servers with hand-edited compose files, .env files containing production passwords, and version: '2' headers. What do you change? Consolidate into one base compose.yaml plus a committed production override, remove the obsolete version field, and pin image tags or digests produced by CI. Move passwords out of .env into secrets written from a secret store at deploy time, rotate the exposed credentials, and keep only non-secret settings in environment files. Deploy from a pipeline that runs docker compose config and up -d, and if the service needs high availability or more hosts, plan a move to a managed container platform or Kubernetes rather than stretching Compose.