17.3.1.5 Compose Environment Files

Compose environment files, as a best practice, means consistently using the env_file directive to reference well-organized, purpose-specific files rather than scattering an ever-growing list of individual key-value pairs directly within each service's inline environment block, keeping configuration both more maintainable and more clearly separated by concern.

Preferring env_file over a long inline list

A service with more than a handful of environment variables becomes considerably harder to scan and maintain as an inline list grows, compared to referencing a dedicated file specifically organized for that purpose:

services:
  api:
    environment:
      - LOG_LEVEL=info
      - DATABASE_URL=postgres://db:5432/app
      - REDIS_URL=redis://cache:6379
      - JWT_EXPIRY=3600
      - FEATURE_NEW_CHECKOUT=false
      - FEATURE_DARK_MODE=true

services:
  api:
    env_file:
      - api.env

The second version keeps the Compose file itself focused on the service's structural definition, image, ports, volumes, dependencies, while the actual configuration values live in a dedicated, independently maintainable file that can be organized, commented, and reviewed on its own terms.

Organizing multiple env files per service by concern

A service can reference more than one env_file, which allows separating genuinely distinct categories of configuration, base application settings, feature flags, environment-specific overrides, into their own, independently maintained files rather than mixing every concern into a single, undifferentiated list:

services:
  api:
    env_file:
      - common.env
      - production.env
      - feature-flags.env

This separation makes it considerably easier to review a change scoped to just one category, a feature flag toggle, for instance, without that change being buried within a much larger file covering many unrelated concerns simultaneously.

Keeping secrets out of env_file-referenced files

Files referenced through env_file should still contain only ordinary, non-sensitive configuration; genuine secrets belong in Docker's dedicated secrets mechanism or an external secrets manager, never mixed into the same file as ordinary configuration values, since env_file content still becomes a plain environment variable, visible through docker inspect, with none of the additional protection a proper secrets mechanism provides:

# api.env
LOG_LEVEL=info
DATABASE_HOST=db

services:
  api:
    env_file:
      - api.env
    secrets:
      - db_password

Keeping this separation explicit and consistent, ordinary configuration through env_file, sensitive credentials through the dedicated secrets mechanism, avoids the common, easy mistake of treating an env_file as a convenient catch-all for every kind of value regardless of its actual sensitivity.

Validating referenced files exist before relying on them

A Compose stack referencing an env_file that does not actually exist at the expected path fails clearly at startup, which is the correct, fail-fast behavior, but confirming this explicitly as part of a deployment pipeline's own pre-flight checks catches the issue before an actual deployment attempt rather than relying on the stack startup failure itself as the first signal:

for f in common.env production.env feature-flags.env; do
  if [ ! -f "$f" ]; then
    echo "ERROR: missing required env file: $f"
    exit 1
  fi
done
docker compose up -d

This kind of explicit pre-flight check is particularly valuable in CI or automated deployment pipelines, where a clear, early failure with a specific, actionable message is considerably more useful than discovering the same gap only through Compose's own, more generic startup error.

Consistent file naming across services

Adopting one consistent naming pattern for environment files across every service in a project, rather than each service inventing its own ad hoc convention, makes the overall project considerably easier to navigate:

api.env
worker.env
scheduler.env

api-config.txt
WorkerEnv.env
scheduler_vars

The first set follows one clear, predictable, consistently applied pattern; the second mixes naming styles and file extensions inconsistently, which makes locating the right file for a given service unnecessarily harder than it needs to be.

Documenting the purpose of each referenced file

For a project with several layered environment files per service, a brief comment or accompanying README entry explaining what each specific file is responsible for prevents confusion about which file is the correct one to modify for a given kind of change:

# common.env: shared, environment-agnostic application defaults
# production.env: production-specific overrides, applied on top of common.env

This kind of brief, direct documentation removes ambiguity about where a specific configuration change actually belongs, which becomes increasingly valuable as the number of layered files for a given service grows.

Common mistakes

• Listing a long, growing set of environment variables inline within a service's environment block rather than organizing them into a dedicated, more maintainable env_file.
• Mixing genuinely distinct categories of configuration, base settings, feature flags, environment-specific overrides, into a single, undifferentiated environment file.
• Including sensitive credential values within an env_file-referenced file rather than using Docker's dedicated secrets mechanism for anything genuinely sensitive.
• Not validating that every referenced environment file actually exists as part of a deployment pipeline's own pre-flight checks, relying entirely on the stack's own startup failure as the first signal of a missing file.
• Using an inconsistent naming convention for environment files across different services within the same project.

Compose environment files, used well, keep ordinary, non-sensitive configuration organized into well-named, purpose-specific files referenced consistently through env_file, with genuine secrets handled entirely separately through a dedicated mechanism, and with deployment pipelines validating these files actually exist before relying on them rather than discovering a gap only through a stack startup failure.