How to make your Docker builds configurable

Docker provides several options for configuring your builds and runtime containers. In this article, I'll try to help you understand the use cases and footguns for every available method.

First, let's look at some common mistakes that developers run into.

Common mistakes

• Docker build images cannot read environment variables. That's right, running NEXT_PUBLIC_DOMAIN=foo.com docker build . is not going to work even if you have an ENV NEXT_PUBLIC_DOMAIN instruction in your Dockerfile.
• Do not store sensitive data in ENV instructions. To illustrate the problem, build a Dockerfile with an ENV TOKEN=xyz instruction, then run docker inspect [image]. You will be able to view your token in plain text. Note that I'm only referring to build environment variables, not runtime environment variables i.e. docker run -e TOKEN.
• Do not use Docker build arguments i.e. ARG token for passing secrets to a build. Build arguments are embedded in the image. An attacker can in some cases run docker history to see your secrets if you do this.
• Do not COPY a .env file or any other file with credentials into your build. No matter what you do, Docker layer caching will leak the contents of these files. COPY instructions should never be used with sensitive data.

Now that we know what not to do, let's look at how to do things the right way.

The right way to configure with Docker

Build arguments ARG

Docker Build Arguments are useful for configuring builds when the configuration values you're passing to the build are not secrets. Examples for this include image versions, build and start commands, and public environment variables required by your build command (e.g. PUBLIC_DOMAIN). FlexStack makes extensive use of build arguments in order to make our autogenerated Dockerfiles configurable.

ARG instructions can be read by other instructions in the Dockerfile, but cannot be read from within containers themselves. Let's look at some examples.

Configuring images

In this example, we're setting two build arguments: one for the version and one for the builder image. We are using default values for each, but these are optional. You can omit default values if you want Docker to complain if they are not provided.

ARG VERSION=3.12
ARG BUILDER=docker.io/library/python
FROM ${BUILDER}:${VERSION}-slim

To override the default values during a build, you can add them to the build command with the --build-arg option.

docker build --build-arg "VERSION=3.10" --build-arg "BUILDER=python"

Adding environment variables to build commands

You can leverage build arguments to add configurations to your build commands (for example next build) by forwarding their values to build-time environment variables.

ARG NEXT_PUBLIC_DOMAIN=flexstack.com \
    NEXT_PUBLIC_SANITY_PROJECT_ID
ENV NEXT_PUBLIC_DOMAIN=${NEXT_PUBLIC_DOMAIN} \
    NEXT_PUBLIC_SANITY_PROJECT_ID=${NEXT_PUBLIC_SANITY_PROJECT_ID}
RUN npm run build

# OR

ARG NEXT_PUBLIC_DOMAIN=flexstack.com \
    NEXT_PUBLIC_SANITY_PROJECT_ID
RUN NEXT_PUBLIC_DOMAIN=${NEXT_PUBLIC_DOMAIN} \
    NEXT_PUBLIC_SANITY_PROJECT_ID=${NEXT_PUBLIC_SANITY_PROJECT_ID} \
    npm run build

To override the default argument values, run:

docker build --build-arg "NEXT_PUBLIC_SANITY_PROJECT_ID=pz123"

Build secrets --secret

Sometimes our build steps need to utilize secrets in order to perform tasks like installing private packages during CI/CD. For these use cases, Docker has provided us with Build Secrets.

Build secrets rely on SSH mounts in order to prevent secrets from being leaked through image layers or the final image.

Mount a secret from the host environment

Let's assume we are building an image in a CI/CD workflow, such as a GitHub Action. GitHub Actions allow users to inject secrets into run commands via environment variables. Getting these secrets into our Dockerfile securely is pretty straightforward.

Our workflow could look like:

steps:
  # Reads the secret from the host environment and provides a 
  # mount point with the ID "NPM_TOKEN"
  - run: docker build --secret id=NPM_TOKEN,env=NPM_TOKEN --secret id=OTHER_TOKEN,env=OTHER_TOKEN .
  - env:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      OTHER_TOKEN: ${{ secrets.OTHER_TOKEN }}

And in our Dockerfile:

# Mount the secret with the ID NPM_TOKEN to this instruction
RUN --mount=type=secret,id=NPM_TOKEN \
    --mount=type=secret,id=OTHER_TOKEN \
    # Export each mounted secret as an environment variable
    # with the same name as the secret ID.
    for f in /run/secrets/*; do export $(basename $f)=$(cat $f); done && \
    # Run the command that needs to use the environment variables
    npm install

# OR:

RUN --mount=type=secret,id=NPM_TOKEN \
    --mount=type=secret,id=OTHER_TOKEN \
    NPM_TOKEN="$(cat /run/secrets/NPM_TOKEN)" npm install

Mount a .env file with credentials

Next, let's consider a case where you're building an image locally. You've got a .env file that contains some credentials and you'd like to get the file into your container build securely, so that some build command can read the contents of the file. With Docker, we can configure source files for secrets and change where Docker mounts them within the container.

In the Dockerfile below we can see that the secret is being mounted to the target /build/.env. We are making an assumption that the build command knows this and will read the contents of the file from that mount target.

# "target=/build/.env" changes the mount point for the secret
# with the id "_env". Instead of `/run/secrets/_env`, the file
# will be written to `/build/.env`
RUN --mount=type=secret,id=_env,target=/build/.env \
    npm run build

And in our build command we can set a source for the file:

# `src=...` tells Docker where it can read the secret file
docker build --secret id=_env,src=$HOME/code/my-app/.env

Runtime environment variables -e

As engineers, we want to be able to securely pass database credentials, service endpoints, ports, and other configuration to our applications at runtime. That is, when we start our application and start using it. In this case, we can finally rely on environment variables to do the work for us, as Docker allows us to set environment variables in its docker run command.

# Use environment variables that are set in the host environment
docker run -e DB_PASSWORD -e DB_HOST my-app:latest

# Inline an environment variable
docker run -e "DB_PASSWORD=abc" -e "DB_HOST=db.internal" my-app:latest