How do you handle configuration and secrets in Docker?

Question

Accepted Answer

Containerized applications should be **configurable** without rebuilding the image — using **environment variables**, config files, and proper **secrets management**. Handling configuration and secrets correctly is important for security and for running the same image across environments.

## Configuration via environment variables (12-factor)

```bash
# pass config at RUNTIME via environment variables (not baked into the image)
docker run -e DATABASE_URL=postgres://... -e NODE_ENV=production myapp
docker run --env-file .env myapp        # load many from a file
```

```yaml
# in docker-compose.yml
services:
  app:
    image: myapp
    environment:
      - DATABASE_URL=postgres://db:5432/app
    env_file: .env
```

Following **twelve-factor** principles, configuration comes from the **environment** (env vars) at runtime — so the SAME image runs in dev, staging, and production with different config, never rebuilding per environment.

## Secrets: do NOT bake them into images

```text
⚠️ NEVER put secrets (passwords, API keys, tokens) in the Dockerfile or image layers:
  → image layers are inspectable → secrets can be EXTRACTED (even if "removed" later,
    they remain in earlier layers)
  → anyone with the image gets the secrets
→ This is a serious, common security mistake.
```

## Proper secrets handling

```text
✓ RUNTIME environment variables (better than image, but visible in inspect/env)
✓ DOCKER SECRETS (Swarm) / Kubernetes Secrets — mounted securely at runtime
✓ Secrets MANAGERS — HashiCorp Vault, AWS Secrets Manager, etc. (fetch at runtime)
✓ BuildKit build secrets (--secret) — for build-time secrets without baking into layers
✓ Keep .env files OUT of version control (.gitignore) and out of the image (.dockerignore)
```

## Why it matters

Handling configuration and secrets correctly in Docker is important for both **security** and **operational flexibility**, so it's valuable practical knowledge.

The configuration principle — providing config via **environment variables at runtime** rather than baking it into the image (following twelve-factor principles) — is important because it lets the **same image run across all environments** (dev, staging, production) with different configuration, never rebuilding per environment, which is fundamental to reproducible, portable deployments and a core containerization practice.

More critically, **secrets handling** is a serious security concern: the key rule — **never bake secrets (passwords, API keys, tokens) into images** — is essential because image layers are inspectable and secrets embedded in them can be **extracted** (and remain in earlier layers even if "removed" later), so anyone with the image gets the secrets; this is a common, dangerous mistake that causes real credential leaks.

Understanding **proper secrets handling** — runtime environment variables (better, though visible in inspect), dedicated secrets mechanisms (Docker/Kubernetes Secrets mounted securely, secrets managers like Vault or AWS Secrets Manager fetched at runtime, BuildKit build secrets for build-time needs), and keeping `.env` files out of version control and images — is necessary to manage secrets securely.

Since running the same image across environments (via env-based config) and protecting secrets (never embedding them in images) are both important for secure, flexible containerized deployments, and since mishandling secrets is a serious, common security failure, understanding configuration and secrets handling in Docker — environment-based config and proper secrets management — is valuable, practically-important knowledge for deploying containers securely and flexibly, with the secrets aspect in particular being critical security knowledge that prevents real credential exposure.