Q: Your organization had an API key accidentally committed to GitHub because a developer used `.env` files interchangeably between Docker Compose, Dockerfiles, and runtime environments. Another team baked database passwords into an image using `ENV DB_PASSWORD=secret`. Development teams are confused about variable precedence, layer caching impacts, and runtime visibility. You must establish a clear configuration architecture distinguishing build-time arguments, runtime variables, and secret injection.

Establish strict architectural boundaries: `ARG` is build-time only (accessible during `docker build`, baked into metadata). `ENV` is build-time AND runtime (persists in running containers and image config). `.env` is Compose interpolation only (expands variables inside `compose.yaml`). Secrets managers inject credentials at runtime outside the image.

<!-- Configuration Scope Matrix -->
Mechanism   Build Phase  Runtime Phase  Image Metadata?  Security Level
ARG         YES          NO             YES (Plaintext)  Low (No secrets!)
ENV         YES          YES            YES (Plaintext)  Low (No secrets!)
.env file   NO (Compose) NO             NO               Medium (Compose syntax only)
Secret Mount YES         NO             NO               High (BuildKit RAM)
Vault/K8s   NO           YES            NO               High (Runtime In-Memory)

Use `ARG` strictly for non-sensitive parameters such as package versions, compiler flags, and target environments.

# Dockerfile
ARG NODE_VERSION=20.11.0
FROM node:${NODE_VERSION}-alpine
ARG BUILD_COMMIT=unknown
ENV APP_COMMIT=${BUILD_COMMIT}  # Safe: Git SHA is not sensitive
WORKDIR /app

Inject non-sensitive runtime configurations (port numbers, log levels, service URLs) via container runtime flags or environment files without hardcoding in the image.

# docker-compose.yml
services:
  api:
    image: my-api:latest
    environment:
      - PORT=8080
      - LOG_LEVEL=info
      - DB_HOST=postgres.internal
    env_file:
      - .env.production  # Non-sensitive environment configuration

For API keys, private certificates, and passwords, never use `ENV` or `.env`. Inject credentials as in-memory files at runtime using Docker Compose secrets, HashiCorp Vault Agent, or AWS Secrets Manager.

    secrets:
      - db_password

secrets:
  db_password:
    file: /secure/vault/db_password.txt