6.1.2.4 Runtime Environment Injection

Runtime environment injection is the practice of supplying configuration values to a container at the moment it starts — rather than baking them into the image — using environment variables, mounted configuration files, or orchestrator-managed configuration, allowing the same image to behave differently across different deployment environments.

Injecting Values Through Environment Variables

The most common form of runtime injection passes configuration directly as environment variables at container start time.

docker run -e DATABASE_URL=postgres://prod-db:5432/app -e LOG_LEVEL=warn myapp:1.0

The same image, started with different environment variables, behaves appropriately for whatever environment it's being run in, without needing a separate image built specifically for that environment.

Injecting Configuration Through an Environment File

For configurations involving many variables, an environment file can be supplied instead of listing each variable individually on the command line.

DATABASE_URL=postgres://prod-db:5432/app
LOG_LEVEL=warn
CACHE_TTL=3600

docker run --env-file production.env myapp:1.0

Injecting Configuration Through Mounted Files

Some applications expect configuration as a file rather than environment variables, which can be supplied through a mounted volume or bind mount pointing to an environment-specific configuration file.

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

Why Runtime Injection Is Preferable to Baking Configuration Into the Image

Building a separate image for each deployment environment, with environment-specific configuration hardcoded inside, multiplies the number of images that need to be built, tested, and maintained — runtime injection instead allows one single, well-tested image to be deployed correctly across every environment simply by varying its runtime configuration.

docker run --env-file staging.env myapp:1.0
docker run --env-file production.env myapp:1.0

Why Runtime Environment Injection Matters

Separating an image's build-time identity from its environment-specific runtime configuration is a foundational practice for deploying the same tested artifact consistently across multiple environments, avoiding the risk and overhead of maintaining environment-specific image variants.