Environment Variables

An environment variable is a name and a value that the operating system hands to a process when it starts. The process reads them the way it reads any other input. Docker sets them when it creates a container, which makes them the usual way to tell one image how to behave in a particular place.

That is the point of the technique. One image, built once and tested once, moves from development to staging to production unchanged. The database host, the log level and the feature flags arrive from outside it. Build a separate image per environment instead and you have three artefacts that were never tested together, and the one you tested is not the one you shipped.

You have already used this without dwelling on it. POSTGRES_PASSWORD and POSTGRES_DB in the earlier lessons are environment variables the PostgreSQL image reads on first start. Images you did not write are configured the same way as images you did.

# One flag per variable
docker run -d --name employees-api --network employees-net -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Staging \
  -e ASPNETCORE_HTTP_PORTS=8080 \
  -e "ConnectionStrings__Employees=Host=db;Port=5432;Database=employees;Username=api_user;Password=local-dev-placeholder" \
  -e Logging__LogLevel__Default=Warning \
  anvi/employees-api:1.4.0

# The same settings collected in a file: one NAME=value per line, no quotes
cat config/api.staging.env
# ASPNETCORE_ENVIRONMENT=Staging
# ASPNETCORE_HTTP_PORTS=8080
# Logging__LogLevel__Default=Warning

docker run -d --name employees-api --network employees-net -p 8080:8080 \
  --env-file config/api.staging.env \
  anvi/employees-api:1.4.0

# Pass a value through from the shell that ran the command
docker run --rm -e ASPNETCORE_ENVIRONMENT alpine:3.20 printenv ASPNETCORE_ENVIRONMENT

# What a container was actually given, including defaults from the image
docker inspect -f '{{json .Config.Env}}' employees-api
docker exec employees-api printenv ASPNETCORE_ENVIRONMENT

• -e NAME=value sets one variable. Repeat the flag for each one — there is no comma-separated form, and a second -e does not replace the first.
• The connection string is wrapped in quotes because it contains semicolons, which your shell would otherwise read as command separators. Quote the whole NAME=value, not only the value.
• --env-file reads NAME=value lines. Docker does not strip quotes inside that file, so a value written with quotes around it keeps them. This surprises people, and the symptom is a password that is wrong by exactly two characters.
• -e NAME with no equals sign copies whatever the calling shell has for that name. It keeps secrets out of scripts and command history, and it fails quietly when the variable was never set.
• docker inspect shows the environment the container was created with, including anything ENV put in the image. Read this before concluding the application ignored a setting — usually the setting never arrived.
• printenv inside the container is the same answer from the other side. Both are worth knowing, because one works on a stopped container and the other proves what the running process can see.

ASP.NET Core reads configuration from several sources and merges them into one set of keys. Keys are hierarchical, written with a colon: ConnectionStrings:Employees names the Employees entry inside the ConnectionStrings section of appsettings.json.

A colon is not a usable character in an environment variable name on every platform, so the environment variable provider accepts two underscores in its place. ConnectionStrings__Employees becomes ConnectionStrings:Employees before the rest of the application sees it. Nesting goes as deep as you need, two underscores per level.

By default the environment variables are added after the JSON files, so a variable wins over the same key in appsettings.json. That is what makes the technique work: the file holds development defaults and stays in the repository, and the environment supplies what is different about each place the image runs.

services:
  api:
    image: anvi/employees-api:1.4.0
    env_file:
      - ./config/api.common.env
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      ASPNETCORE_HTTP_PORTS: "8080"
      Logging__LogLevel__Default: Information
      ConnectionStrings__Employees: Host=db;Port=5432;Database=employees;Username=api_user;Password=${POSTGRES_PASSWORD}
    ports:
      - "8080:8080"

• environment takes a mapping of names to values. A list of NAME=value strings works too; the mapping form is easier to read once the values get long.
• 8080 is quoted. Environment variables are text by definition, and YAML would otherwise read an unquoted 8080 as a number — quote anything that looks like a number, a version or a boolean.
• The ${POSTGRES_PASSWORD} placeholder is substituted by Compose before the container is created, from your shell or from a .env file next to the Compose file. The application never sees the placeholder, only the value.
• A name Compose cannot substitute becomes an empty string with a warning rather than an error. The container then starts with a blank password and fails later, somewhere less obvious.
• env_file paths are relative to the Compose file. Names set in environment override the same names from env_file, which is the precedence from the list above expressed in one place.
• The Docker Compose lesson builds this out into the full multi-service file. The configuration shape does not change when it gets there.