Managing Environment Variables: A Docker Configuration Guide

Previously in this course, we covered Building Your First Image and learned how to package your code into a portable format. Today, we take that portability a step further by decoupling your application's configuration from its code using environment variables.

In modern cloud-native development, you should never hard-code settings like API keys, database URLs, or feature flags directly into your source code. If you do, changing a single configuration value requires a full image rebuild. By using environment variables, you inject configuration at runtime, allowing the same container image to run in development, staging, and production environments without modification.

The Two Layers of Configuration

Docker gives you two primary ways to set environment variables: during the build process (via the Dockerfile) or at runtime (via the Docker CLI).

1. Setting Defaults in the Dockerfile

The ENV instruction in a Dockerfile sets a default value for an environment variable. If you don't provide an override when starting the container, your application will use this value.

Create a simple app.py script to test this:

PYTHON
import os

# Accessing an environment variable
app_color = os.getenv(CE9178">'APP_COLOR', CE9178">'blue')
print(f"The app is running with color: {app_color}")

Now, create a Dockerfile to set a default:

Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY app.py .
# Set the default value
ENV APP_COLOR=blue
CMD ["python", "app.py"]

Build and run this image:

Bash
docker build -t my-config-app .
docker run --rm my-config-app
# Output: The app is running with color: blue

2. Injecting Variables at Runtime

The power of environment variables comes from the ability to override those defaults when you start the container. You use the -e (or --env) flag to pass new values to the container process.

Run your container again, but this time, change the color:

Bash
docker run --rm -e APP_COLOR=red my-config-app
# Output: The app is running with color: red

Because we used -e, the container ignored the blue default defined in our Dockerfile and used red instead. This is the core of "build once, run anywhere."

Accessing Variables Inside a Container

Once a variable is injected, it becomes part of the process's environment. You can verify this by checking the shell inside a running container.

If you have a container running, you can use the env command via docker exec:

Bash
# Start a container in detached mode
docker run -d --name env-test -e MY_SECRET=supersecret alpine sleep 3600

# Inspect the environment
docker exec env-test env

You will see MY_SECRET=supersecret listed in the output, along with other default environment variables provided by Docker.

Hands-On Exercise

1. Modify your app.py to print a second variable named DB_HOST with a default of localhost.
2. Update your Dockerfile to set this default using the ENV directive.
3. Build the image again.
4. Run the container, overriding both APP_COLOR and DB_HOST using multiple -e flags: docker run -e APP_COLOR=green -e DB_HOST=db.production.example.com <your-image-name>

Common Pitfalls

• Sensitive Data: Never hard-code production passwords or sensitive API tokens in your Dockerfile using ENV. Because Dockerfile instructions are stored as image layers, anyone with access to the image can view these values by inspecting the image history. For real secrets, we will look at more secure methods in later lessons.
• Variable Names: Environment variables are case-sensitive. APP_COLOR and app_color are treated as different keys by your operating system.
• Shell Expansion: Be careful when passing variables from your host shell. If you run docker run -e MY_VAR=$HOST_VAR, your host shell will evaluate $HOST_VAR before it ever reaches Docker. Use quotes if you need to pass literal values containing special characters.

FAQ

Q: Can I set environment variables for a container that is already running? A: No. Environment variables are part of the process environment and are set when the process starts. To change them, you must stop the container and run a new instance with the updated -e flags.

Q: Where should I define configuration if I have dozens of variables? A: Passing dozens of -e flags becomes unmanageable. We will cover using .env files and Docker Compose to manage larger configurations in upcoming lessons, such as Managing Secret Configuration.

Recap

You’ve learned that environment variables are the bridge between your static image and its dynamic execution environment. By using ENV in your Dockerfile, you set sensible defaults, and by using the -e flag, you maintain the flexibility to deploy the same image across different environments. You are now ready to handle more complex service relationships.

Up next: Working with Container Logs