1.2.2.3 Configuration Packaging

Configuration packaging is the practice of defining how an application's configuration — environment variables, config files, feature flags — is provided to a container, in a way that keeps the application image itself reusable across environments while still allowing each environment to be configured differently.

Configuration Belongs Outside the Image

Unlike dependencies, which should be fixed and identical everywhere, configuration is expected to differ between environments: a database connection string in staging is not the same as in production. Baking environment-specific configuration directly into an image would defeat the purpose of building one image and deploying it everywhere, since a new image would be needed for every environment.

FROM node:20-alpine
COPY . /app
WORKDIR /app
RUN npm install
CMD ["node", "server.js"]

This image contains no environment-specific values; they are supplied separately when a container is started from it.

Supplying Configuration at Run Time

Environment variables are the most common way to pass configuration into a container without modifying the image.

docker run -e DATABASE_URL=postgres://db:5432/staging -e LOG_LEVEL=debug myapp
docker run -e DATABASE_URL=postgres://db:5432/prod -e LOG_LEVEL=warn myapp

The same image produces two differently configured containers, with the difference living entirely outside the image.

Packaging Configuration Files Separately

For configuration that is more naturally expressed as a file rather than individual variables, a file can be mounted into the container at run time instead of being copied in during the build.

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

Using Compose to Organize Configuration Per Environment

docker compose files, or multiple compose files layered together, let a project define configuration once per environment without duplicating the rest of the service definition.

services:
  app:
    image: myapp:latest
    env_file: .env.production

docker compose --env-file .env.staging up

Secrets Require Special Handling

Sensitive configuration — passwords, API keys, certificates — should not be packaged into the image or passed as plain environment variables visible in process listings; container orchestrators typically provide a dedicated secrets mechanism for this case.

docker secret create db_password ./db_password.txt
docker service create --secret db_password myapp

Why Separating Configuration Matters

Keeping configuration outside the image is what allows a single built and tested image to be promoted unchanged from staging to production: only the configuration supplied at run time changes, not the application artifact itself.