Using Docker Env Files with --env-file

Managing Configuration with Env Files

When a container needs many environment variables, listing them all with -e flags becomes unwieldy. The --env-file flag loads variables from a file:

docker run -d --env-file ./app.env my-app

Env File Format

The file follows a simple KEY=VALUE format, one variable per line:

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASS=secretpassword
DB_NAME=myapp

# Application settings
NODE_ENV=production
PORT=3000
LOG_LEVEL=info

# External services
REDIS_URL=redis://cache:6379
SMTP_HOST=mail.example.com

File Format Rules

• Lines starting with # are comments (ignored).
• Empty lines are ignored.
• Each line must be KEY=VALUE format.
• Quotes around values are included literally (KEY="value" sets the variable to "value" including the quotes in some Docker versions).
• No variable expansion ($VAR references are not resolved).

Multiple Env Files

You can specify multiple --env-file flags. Later files override earlier ones for duplicate keys:

docker run -d \
  --env-file ./base.env \
  --env-file ./production.env \
  my-app

A common pattern is to have a base configuration with environment-specific overrides:

base.env          # Shared defaults
development.env   # Dev-specific overrides
staging.env       # Staging overrides
production.env    # Production overrides

Precedence Rules

When the same variable is defined in multiple places, this is the precedence (highest wins):

1. -e KEY=VALUE on the command line
2. --env-file (later files override earlier ones)
3. ENV instruction in the Dockerfile

# CLI flag wins over env file
docker run -e LOG_LEVEL=debug --env-file ./production.env my-app
# LOG_LEVEL will be 'debug' even if production.env says 'info'

Environment-Specific Files

Organize your env files by environment:

config/
  base.env           # DB_HOST, REDIS_URL, etc.
  development.env    # LOG_LEVEL=debug, NODE_ENV=development
  production.env     # LOG_LEVEL=warn, NODE_ENV=production
  secrets.env        # API_KEY, DB_PASS (never committed to git)

Security Best Practices

• Never commit secrets.env to version control. Add it to .gitignore.
• Use .env.example as a template with placeholder values for documentation.
• On CI/CD systems, inject secrets from a vault (HashiCorp Vault, AWS Secrets Manager) into env files at deploy time.
• Restrict file permissions: chmod 600 secrets.env.
• Periodically rotate secrets and update env files accordingly.