Docker Compose Environments and Variables

What this article covers

• How Compose uses environment variables.
• Differences between env_file, environment, and .env.
• Using profiles for optional services.
• Override files for local development.
• Managing multiple environments with Compose.

Introduction: Docker Compose environments and variables

Docker Compose makes it straightforward to start multiple containers together. When the same Compose file needs to run across different environments, you need a clean way to adjust configuration. Environment variables, env files, Compose profiles, and override files help keep things organized and prevent duplicating the same configuration over and over.

This article shows how to work flexibly with environments and variables in Docker Compose.

Key terms

• .env: Standard file for Compose variables.
• env_file: File containing variables for a service.
• environment: Variables set directly in a service definition.
• Variable substitution: Using ${VAR} in Compose files.
• Profiles: Optional groups of services.
• Override: Additional file that extends base Compose configuration.
• Default value: Value used if a variable is not set.
• Shell variable: Variable from the shell environment.

.env in your project

A .env file in the same directory as compose.yaml populates variables:

APP_PORT=3000
DB_NAME=meine_db
DB_PASSWORD=geheim

In compose.yaml:

services:
  app:
    image: app:latest
    ports:
      - "${APP_PORT}:3000"
    environment:
      DB_NAME: ${DB_NAME}
      DB_PASSWORD: ${DB_PASSWORD}

Default values

ports:
  - "${APP_PORT:-3000}:3000"

If APP_PORT is not set, port 3000 is used as the fallback.

env_file per service

services:
  db:
    image: postgres:16
    env_file:
      - db.env

The db.env file contains variables specific to this service only.

Setting environment variables directly

services:
  app:
    image: app
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info

Mixing approaches is possible but quickly becomes hard to follow.

Compose profiles

Profiles let you start services conditionally:

services:
  web:
    image: nginx
    profiles:
      - web
  monitoring:
    image: prometheus
    profiles:
      - monitoring

Start with a profile:

docker compose --profile monitoring up -d

Multiple Compose files

docker compose -f compose.yaml -f compose.prod.yaml up -d

compose.prod.yaml overrides or extends settings from the base file.

Override files

Docker Compose automatically loads compose.override.yaml if it exists:

# compose.override.yaml (local)
services:
  app:
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=1

This keeps development customizations out of your production configuration file.

Different environments

.
├── compose.yaml
├── compose.dev.yaml
├── compose.prod.yaml
├── .env.dev
└── .env.prod

Start:

docker compose -f compose.yaml -f compose.prod.yaml --env-file .env.prod up -d

Tips

• Never commit .env files to Git.
• Maintain clear separation between local and production files.
• Use default values to prevent errors.
• Store secrets in Docker Swarm or external vaults instead of configuration files.
• Use consistent naming conventions for variables.
• Use profiles for optional tools.

Common gotchas

• .env is not loaded: The file must be in the current directory.
• Variables are undefined: Variable substitution fails.
• Wrong YAML formatting: Confusing environment with env_file.
• Secrets in .env: A security risk.
• Override is loaded automatically: Unexpected configuration is applied.
• Whitespace in values: For example, avoid spaces around = in environment.

Further reading and resources

• BotServ.de Docker Compose
• BotServ.de Docker Secrets
• BotServ.de dotenvx
• BotServ.de Docker Commands

FAQ: Compose environments

What’s the difference between .env and env_file? .env defines variables for Compose itself, while env_file passes variables to the container.

Can I use multiple .env files? Yes, use the --env-file flag.

Are override files loaded automatically? Yes, compose.override.yaml is loaded automatically.

What are Compose profiles? Optional groups of services that only start when explicitly requested.

Should I use environment in compose.yaml? Only for non-sensitive values. Never store secrets there.

Sources and further reading

• Compose Env: https://docs.docker.com/compose/environment-variables/
• Compose Profiles: https://docs.docker.com/compose/profiles/
• Multiple Compose Files: https://docs.docker.com/compose/multiple-compose-files/

Summary: Docker Compose environments and variables

Docker Compose offers many ways to control configuration through variables and files. Use .env for Compose-level variables, env_file for service environments, profiles for optional services, and override files for local adjustments. When you maintain clear separation and keep secrets out of version control, you can elegantly manage multiple environments with the same base configuration.