Inline environment vs env_file

Docker Compose supports two ways to pass environment variables. The 'environment' key lists variables directly in docker-compose.yml as KEY: VALUE pairs. The 'env_file' key references an external .env file. Inline is convenient for non-sensitive config that should be version-controlled. env_file is better for secrets because you can .gitignore the file. You can use both together — inline values override env_file values for the same key.

# Inline environment
services:
  app:
    image: node:20
    environment:
      NODE_ENV: production
      PORT: 3000

# env_file reference
services:
  app:
    image: node:20
    env_file:
      - .env
      - .env.local

Variable interpolation in Compose

Docker Compose supports variable substitution using ${VARIABLE} syntax in the YAML file itself. Variables are resolved from the shell environment or a .env file in the project root (not the env_file directive). You can set defaults with ${VARIABLE:-default} and require values with ${VARIABLE:?error message}. This is useful for per-environment configuration without changing the compose file.

services:
  db:
    image: postgres:${POSTGRES_VERSION:-16}
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD:?Set DB_PASSWORD in .env}

Security best practices

Never commit secrets to docker-compose.yml. Use env_file with .gitignore for local development. For production, use Docker Swarm secrets, external secret managers (Vault, AWS Secrets Manager), or build-time --secret mounts. The converter detects sensitive keys like passwords, tokens, and API keys and flags them in the output.