4.2.8.3 ENV App Config

ENV app config refers to using ENV-set environment variables as the primary mechanism for configuring an application's behavior across different environments, a widely adopted pattern that keeps configuration external to the image itself while still letting the image declare sensible defaults.

The Pattern in Practice

An application reads its configuration from environment variables at startup, with the image providing reasonable defaults through ENV and each deployment environment supplying its own specific overrides at run time.

ENV DATABASE_URL=postgres://localhost:5432/app
ENV CACHE_TTL=300
ENV FEATURE_NEW_UI=false

docker run -e DATABASE_URL=postgres://prod-db:5432/app -e FEATURE_NEW_UI=true myapp:1.0

The same image serves both a local development scenario (using its built-in defaults) and a production deployment (using explicitly supplied overrides), without any difference in the image itself.

Why This Pattern Is Widely Adopted

Configuring applications through environment variables, rather than baking environment-specific configuration files directly into separate images per environment, means a single image can be built once and promoted unchanged across every environment it needs to run in.

docker run -e DATABASE_URL=$STAGING_DB_URL myapp:1.0
docker run -e DATABASE_URL=$PROD_DB_URL myapp:1.0

Limitations of Environment Variable Configuration

Environment variables are well suited to simple key-value configuration but become unwieldy for more complex, structured configuration, which is often better expressed as a mounted configuration file rather than an excessive number of individual environment variables.

docker run -v ./config.yaml:/app/config.yaml myapp:1.0

Combining Defaults With Required Overrides

A practical convention separates configuration into defaults baked into the image via ENV (suitable for any environment) and values that must always be explicitly supplied per deployment (secrets, environment-specific endpoints), making the distinction clear to anyone deploying the image.

Why This Pattern Matters

Treating environment variables as the primary application configuration mechanism is one of the most widely adopted conventions in containerized application design, directly supporting the broader goal of building one image and deploying it consistently across every environment it needs to run in.