Chapter 5b of 17 · Visual guide

Environment variables

Build one image, then configure it differently for development, staging and production without rebuilding. Environment variables are how you hand that configuration in.

key idea / Docker itselfcontainer / good pathhost / watch outproblem / blockedneutral

What an environment variable is

A named string that the operating system gives a process when it starts. Docker sets them for the container's main process, and your code reads them like any other variable.

PORT=4000
NODE_ENV=production
DB_HOST=postgres

// Node.js
const port = Number(process.env.PORT ?? 4000);   // values are always strings
const dbHost = process.env.DB_HOST;
if (!dbHost) throw new Error('DB_HOST is not set');

app.listen(port);

Where the values come from

Setting them with -e

-e (long form --env) sets one variable. Repeat it for more.

$ docker run -d --name posts \
    -e PORT=4000 \
    -e NODE_ENV=production \
    -e DB_HOST=postgres \
    micro-posts

Give only a name and Docker copies the value from your host shell:

$ export PORT=4000
$ docker run -e PORT micro-posts        # container gets PORT=4000

Many at once: --env-file

Put the values in a file, one KEY=value per line, and pass the file.

# app.env
PORT=4000
NODE_ENV=production
DB_HOST=postgres
DB_PORT=5432

$ docker run --env-file app.env micro-posts

Defaults in the Dockerfile: ENV

ENV bakes a default into the image. Every container started from it gets the value unless docker run overrides it.

FROM node:22
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV PORT=4000 \
    NODE_ENV=production
CMD ["node", "server.js"]

$ docker run micro-posts                  # PORT=4000 (image default)
$ docker run -e PORT=5000 micro-posts     # PORT=5000 (run time wins)

Base images set variables too. node:22 sets NODE_VERSION, and nearly every image sets PATH; you will see them in env output.

ARG versus ENV

ARG VERSION=dev                      # default, overridable at build time
RUN echo "building $VERSION"         # visible here
ENV APP_VERSION=$VERSION             # copy it into ENV to keep it at run time

$ docker build --build-arg VERSION=2.0 -t micro-posts .

One scoping rule: an ARG declared before FROM can only be used in FROM lines. To use it in a later step, declare ARG NAME again (no value) after FROM.

Seeing what a container got

$ docker exec posts env                 # every variable
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=4f1c2a9e8b7d
NODE_VERSION=22...
PORT=4000
NODE_ENV=production
DB_HOST=postgres
...
$ docker exec posts printenv PORT       # just one
4000
$ docker inspect --format '{{json .Config.Env}}' posts   # without entering the container

$ docker exec posts echo $PORT

$ docker exec posts sh -c 'echo $PORT'

Set once, at creation

A container's environment is fixed when it is created. There is no command to change it on a running container, and docker restart keeps the old values. To change a value, remove the container and run a new one.

$ docker rm -f posts
$ docker run -d --name posts -e PORT=5000 micro-posts

Variables set inside a shell with docker exec ... export X=1 disappear when that shell exits; they never reach the main process.

Secrets

Environment variables are not a secure store. Know where each method leaks:

• Never put real secrets in ENV or ARG.
• Local development: an untracked env file with --env-file is fine.
• A secret needed during the build (a private registry token): BuildKit secret mounts, RUN --mount=type=secret,id=npmrc ... with docker build --secret id=npmrc,src=.npmrc. The file is available to that one step and is not saved in a layer.
• Production: the platform's secret store (Kubernetes Secrets, Docker Swarm secrets, AWS Secrets Manager, Vault). These usually mount secrets as files rather than variables.

Try it yourself

1. Step 1 · One variable

   $ docker run --rm -e GREETING=hello alpine:3.20 printenv GREETING
   hello

2. Step 2 · Pass-through from the host

   printenv prints nothing and exits with status 1 when the variable does not exist.

   $ export TEAM=web
   $ docker run --rm -e TEAM alpine:3.20 printenv TEAM
   web
   $ docker run --rm -e NOT_ON_HOST alpine:3.20 printenv NOT_ON_HOST
   $ echo $?
   1

3. Step 3 · An env file keeps quotes

   $ printf '# demo\nMODE="debug"\nLEVEL=2\n' > demo.env
   $ docker run --rm --env-file demo.env alpine:3.20 sh -c 'echo "$MODE $LEVEL"'
   "debug" 2

4. Step 4 · ARG, ENV and an override

   $ mkdir envdemo && cd envdemo
   $ cat > Dockerfile <<'DF'
   FROM alpine:3.20
   ARG VERSION=dev
   ENV APP_VERSION=$VERSION PORT=4000
   CMD ["sh", "-c", "echo version=$APP_VERSION arg=$VERSION port=$PORT"]
   DF
   $ docker build --build-arg VERSION=2.0 -t envdemo .
   $ docker run --rm envdemo
   version=2.0 arg= port=4000
   $ docker run --rm -e PORT=5000 envdemo
   version=2.0 arg= port=5000

   arg= is empty: the ARG existed only during the build. Its value survived because ENV copied it.

5. Step 5 · Whose $PORT?

   $ unset PORT
   $ docker run -d --name api -e PORT=3000 alpine:3.20 sleep 300
   $ docker exec api echo $PORT
   
   $ docker exec api sh -c 'echo $PORT'
   3000
   $ docker rm -f api

Recap

• Same image, different -e / --env-file values per environment. No rebuild.
• Run-time values replace image ENV defaults with the same name.
• -e KEY copies from the host; unset on the host means unset in the container.
• --env-file keeps quotes and does not expand $VARS; docker run never loads .env on its own.
• ARG is build time only; ENV reaches build steps after it and every container.
• Environment is fixed at creation: recreate the container to change it.
• No secrets in ENV or ARG; -e values show in docker inspect.

Quick check