Environment Variables and Configuration

Imagine you’re sending personalized letters to 100 people.

Each letter has:

• Static content — the main message (same for everyone)
• Variable content — the person’s name, address, custom greeting

You could handwrite each letter individually. But that’s tedious.

Instead, you use a template:

Dear {{NAME}},

Thank you for your order of {{PRODUCT}}.
Your delivery address is {{ADDRESS}}.

Then you have a separate list mapping names to values:

NAME=John
PRODUCT=Laptop
ADDRESS=123 Main St

Environment variables are the value list. Your application is the template. At runtime, variables get filled in.

Method 1: Inline in compose file

services:
  app:
    image: myapp
    environment:
      DATABASE_URL: postgresql://db:5432/myapp
      DEBUG: "true"
      API_KEY: secret123

Simple, but secrets are visible in the file.

Method 2: Array syntax

services:
  app:
    image: myapp
    environment:
      - DATABASE_URL=postgresql://db:5432/myapp
      - DEBUG=true

Method 3: From a .env file

Create a .env file:

DATABASE_URL=postgresql://db:5432/myapp
DEBUG=true
API_KEY=secret123

Reference it in compose file:

services:
  app:
    image: myapp
    env_file:
      - .env

Method 4: Shell environment variables

Use ${VARIABLE} syntax in compose file:

services:
  app:
    image: myapp
    environment:
      API_KEY: ${API_KEY}
      DEBUG: ${DEBUG:-false}    # Default to "false" if not set

Set in shell before running:

export API_KEY=secret123
export DEBUG=true
docker compose up

Compose automatically loads a .env file from the same directory as docker-compose.yml.

Example: .env

# Database
POSTGRES_PASSWORD=supersecret
POSTGRES_DB=myapp

# Application
DEBUG=true
API_KEY=abc123

docker-compose.yml

version: '3.9'

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
  
  app:
    image: myapp
    environment:
      DATABASE_URL: postgresql://db:5432/${POSTGRES_DB}
      DEBUG: ${DEBUG}
      API_KEY: ${API_KEY}

Best practices:

1. Add .env to .gitignore — Never commit secrets to git
2. Create .env.example — Template file showing what variables are needed
3. Document required variables — In README or comments

.env.example

# Database Configuration
POSTGRES_PASSWORD=changeme
POSTGRES_DB=myapp

# Application Settings
DEBUG=false
API_KEY=your-api-key-here

Commit .env.example to git, not .env.

Different configurations for different environments:

.env.development
.env.staging
.env.production

Use specific files:

# Development
docker compose --env-file .env.development up

# Production
docker compose --env-file .env.production up

Or use multiple compose files (covered in next chapter).

For sensitive data in production, use Docker secrets (Swarm mode) or external secret managers.

Docker Swarm secrets:

version: '3.9'

services:
  app:
    image: myapp
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    external: true
  api_key:
    external: true

Create secrets:

echo "supersecret" | docker secret create db_password -
echo "abc123" | docker secret create api_key -

Secrets are mounted as files in /run/secrets/ inside the container.

External secret managers (production):

• AWS Secrets Manager
• HashiCorp Vault
• Azure Key Vault

Your application fetches secrets at startup from these services.

---