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.
Topics on this page
Section titled “Topics on this page”| 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. |
What Compose is
Section titled “What Compose is”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.
A complete compose file
Section titled “A complete compose file”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.txtEach 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 execor 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.
Everyday commands
Section titled “Everyday commands”# Not run here: these start containers and need a Docker daemondocker compose up -d # build if needed, create and start everything in the backgrounddocker compose up -d --build api # rebuild and recreate one servicedocker compose ps # status and health of the project's containersdocker compose logs -f api # follow one service's logsdocker compose exec api sh # shell in a running containerdocker compose run --rm api dotnet ef database update # one-off command in a new containerdocker compose restart apidocker compose stop # stop, keep containersdocker compose down # stop and remove containers and networks; keep volumesdocker compose down -v # also delete named volumes (data)docker compose config # validate and print the fully resolved filedocker 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:
upwithout--buildafter changing the Dockerfile. Compose reuses the existing image. Add--build, or use file watch in development.runversusexec.runstarts a new container (with the service’s configuration),execenters an existing one.
Startup order and health checks
Section titled “Startup order and health checks”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 10in 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.
curlis not in many slim images; use a tool the image has, or a small built-in health endpoint client.
Compose files and overrides
Section titled “Compose files and overrides”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 developmentservices: 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/srcFor other environments, name the files explicitly; later files override earlier ones:
services: api: restart: unless-stopped environment: ASPNETCORE_ENVIRONMENT: ProductionORDERS_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.1Maps 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.yamlruns development settings. Use explicit-ffiles outside development. - Divergent copies instead of overrides. Two full compose files drift apart; keep one base file.
Environment variables
Section titled “Environment variables”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.
# Not run heredocker run -e ASPNETCORE_ENVIRONMENT=Staging --env-file ./api.staging.env \ registry.example.test/ordersportal/orders-api:2.4.1In 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
.envfiles with real credentials. Add them to.gitignoreand to.dockerignore. - Expecting changed variables to apply to a running container. Environment is fixed at container creation; recreate the container (
docker compose up -ddoes this when configuration changed).
Interpolation and precedence
Section titled “Interpolation and precedence”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:
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}ORDERS_API_TAG=2.4.0
# api.envLOG_LEVEL=DebugFEATURE_GUEST_CHECKOUT=falseWithout PAYMENTS_URL in the shell, validation fails early:
$ docker compose configerror while interpolating services.api.environment.PAYMENTS_URL: required variable PAYMENTS_URL is missing a value: PAYMENTS_URL must be setWith 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.0LOG_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:
docker compose run -eon the command line.environmentorenv_fileentries whose value is interpolated from the shell or an environment file.- Values set directly in
environment. - Values from
env_file. ENVin the image’s Dockerfile.
Pitfalls:
- Expecting
.envvalues inside the container. Reference them explicitly (LOG_LEVEL: ${LOG_LEVEL}) or useenv_file. - A stray exported shell variable. An old
export ORDERS_API_TAG=...silently overrides.env. Check withdocker compose config.
Secrets
Section titled “Secrets”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_passwordKeep 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.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Docker section start
- Dockerfiles and builds: the build targets Compose uses.
- Docker volumes and networking: the storage and networks Compose creates.
- Kubernetes configuration: ConfigMaps, Secrets, namespaces and Helm: the cluster equivalent of these settings.