Setting Docker Environment Variables: The Ultimate Guide

What Are Docker Environment Variables? 

Environment variables are dynamic-named values that can affect the way running processes behave on a computer. They are part of the environment in which a process runs. For example, a running process can query the value of the HOME environment variable to get the path to the main directory used by the process.

Docker uses environment variables to customize your Docker containers and applications without having to modify your Dockerfiles or container images. In Docker, environment variables can be used to pass configuration settings and other information into Docker containers at runtime. 

Environment variables can be defined in your Dockerfile using the ENV command, or they can be passed into your containers at the command line when you run your containers using the -e option. Once an environment variable has been set, it can be used in your Dockerfile and your application code to dynamically configure your container and application behavior.

Common Use Cases for Docker Environment Variables 

Configuring Software Packages Inside Containers

Many software packages are configured using environment variables, and Docker makes it easy to pass these variables into your containers at runtime.

For example, you might have a Docker container that runs a web server like Apache or Nginx. You can use Docker environment variables to configure the server’s settings, such as the server name, the port it listens on, and the root directory for your website. This allows you to have a single Docker image that can be configured differently for each instance of your container, which can be very useful in testing and production environments.

Related content: Read our guide to testing environments

Dynamically Controlling Container Behavior at Runtime

Control container behavior at runtime can be useful for making changes to a container based on the state of your environment.

For example, you might have a Docker container that runs in different subnets across your network. You can use Docker environment variables to pass information about the current subnet. This could include information like the relative path the container needs to access important resources on the current subnet. 

Overriding Default Settings of Containerized Applications

Finally, Docker environment variables can be used to override the default settings of your containerized applications. This can be useful for customizing your application behavior without having to modify your application code.

For instance, you might have a Docker container that runs an application which has logging turned off by default. When running in a production environment, you can turn on logging, and when running in a testing environment, you can make logging more verbose. This allows you to customize your application behavior in a flexible way, without having to modify the container image.

Passing Secrets and Credentials

Docker environment variables can also be used to pass secrets and credentials into your Docker containers. This is commonly used for sensitive information that should not be hardcoded into Dockerfiles or images for security reasons.

For example, consider a Docker container that connects to a database. You can use Docker environment variables to pass the database connection string, username, and password into your container at runtime. 

However, you should note that saving sensitive information in environment variables is also not secure, because anyone with access to the operating environment can view them. Preferably, such information should be stored using secrets and their data should be encrypted.

Types of Docker Environment Variables 

ARG variables

ARG variables are a type of Docker environment variable that can be used to pass build-time variables into your Dockerfile. They are defined in your Dockerfile using the ARG command, and they can be passed into your build command at the command line using the --build-arg option.

ARG variables are particularly useful for customizing your build process, such as setting the version of a software package to install, the URL of a repository to clone, or the name of a branch to check out. However, they are only available during the build process, and they are not included in the final Docker image or available to your containers at runtime.

ENV variables

ENV variables are another type of Docker environment variable that can be used to pass runtime variables into your Docker containers. They are defined in your Dockerfile using the ENV command, and they can be passed into your run command at the command line using the -e option.

ENV variables are particularly useful for configuring your Docker containers and applications at runtime, such as setting the server name, port, and root directory for a web server, passing secrets and credentials into a database connection, or dynamically controlling the behavior of a microservice. Unlike ARG variables, ENV variables are included in the final Docker image and available to your containers at runtime.

Tips From the Expert

In my experience, here are tips that can help you better set and manage Docker environment variables:

1. Leverage multi-stage builds to isolate ARG variables
   Use multi-stage builds to limit the exposure of build-time ARG variables. This way, ARG variables used in early stages (like downloading dependencies) are not carried into the final image, enhancing security and minimizing overhead.

2. Create separate secrets and configuration layers
   Separate environment variables related to configuration (e.g., ports, file paths) from sensitive data (e.g., passwords, API keys). For secrets, use tools like Docker Secrets or external key management services to prevent exposure in Dockerfiles or environment files.

3. Use docker-compose.override.yml for local overrides
   In development, use docker-compose.override.yml to override environment variables defined in the main docker-compose.yml without editing the original file. This allows for environment-specific changes, such as enabling detailed logging locally without affecting production.

4. Implement variable scoping in multi-container apps
   For multi-container apps in Docker Compose, scope environment variables to specific services by using the environment or env_file attributes under each service. Avoid using a global .env file that may apply unnecessary variables across services.

5. Secure sensitive runtime variables with external stores
   When passing secrets at runtime (e.g., via docker run -e or --env-file), integrate with secret management solutions like AWS Secrets Manager or HashiCorp Vault to inject secrets dynamically, reducing the risk of leaks in local environments or CI/CD systems.

Ran Cohen

CTO & Co-Founder. Configu

Before co-founding Configu, Ran was a full stack developer at Testim.io and previously served in an elite cybersecurity unit in the Israeli Defense Forces.

How to Set Docker Environment Variables 

Let’s review three ways to set environment variables in Docker.

1. Setting ARG Values

ARG, or argument, is a Dockerfile instruction that defines a variable that users can pass at build-time to the builder. These ARG values are not available after the image is built, which makes them ideal for passing build-time variables that don’t need to be included in the final image.

To set an ARG value, you can use the ARG instruction in your Dockerfile. For example, to set a build-time variable called VERSION, you would include the following line in your Dockerfile:

ARG VERSION

Then, when building your image, you can pass the VERSION variable using the --build-arg flag:

docker build --build-arg VERSION=1.0 -t my-app:1.0 .

Here is an example of a Dockerfile with the above ARG instruction:

This is the output when building the image, see how the environment variables are set in steps 3 and 4:

2. Setting ENV Values with the -e Flag

Unlike ARG values, ENV values are environment variables that are available in the built image and can be used by applications running in containers spawned from that image. ENV values are set using the ENV instruction in the Dockerfile.

For example, to set an environment variable named APP_ENV, you would include the following line in your Dockerfile:

ENV APP_ENV production

Here is an example of a Dockerfile with the above APP_ENV instruction:

This will set the APP_ENV variable to production in any containers spawned from the image. You can also override these ENV values when running a container using the -e flag:

docker run -e "APP_ENV=development"  myapp:1.0

This will run the container with the APP_ENV variable set to development, overriding the production value set in the Dockerfile.

3. Using --env-file with Docker Run

When running a Docker container, if you have many environment variables to pass, using the -e flag can become cumbersome.

To simplify this process, Docker provides the --env-file flag, which allows you to pass a file containing all your environment variables. The file should contain one environment variable per line, in the format VAR=VALUE. For example:

DB_USER=root

DB_PASS=secret

APP_ENV=production

Then, you can pass this file to the docker run command as follows (after you have built the image):

docker run --env-file .env myapp:1.0

This will run the container with the environment variables defined in the .env file. The output should look like this:

Best Practices for Setting and Using Environment Variables in Docker 

Here are several best practices that will help you use Docker environment variables more effectively and securely.

Avoid Storing Sensitive Data in Dockerfiles

One of the key rules when dealing with Docker environment variables is to avoid storing sensitive data, such as passwords, API keys, or other secrets, in Dockerfiles. This is because Dockerfiles are often committed to version control systems like Git, which would expose any sensitive data in the Dockerfile to anyone with access to the repository.

As mentioned earlier, saving sensitive information to environment variables is a common practice, and is more secure than storing it in a Dockerfile. However, environment variables are stored in plaintext in your operating system and are visible to anyone with access to your environment. Therefore, prefer to store sensitive data in secrets or using configuration management tools.

Limit Scope of ARG in Dockerfile

As mentioned earlier, ARG values are only available during the build process and are not included in the final image. However, it’s important to be aware that ARG values can be accessed in any subsequent layers of the build process after they are defined.

To limit the scope of ARG values and enhance security, you should define ARG values as close as possible to where they are used in the Dockerfile, and avoid using them in intermediate layers that don’t require them.

Keep Docker Compose Configuration Clear

When using Docker Compose to manage multi-container applications, it’s important to keep your Compose configuration clear and easy to understand. This includes how you handle environment variables.

Docker Compose allows you to define environment variables in several ways, including in the Compose file itself, in separate environment files, or using variable substitution in the Compose file. You should choose one method and stick to it, to avoid confusion or possible misconfigurations.

Learn more in our detailed guide to docker compose environment variables

Consider Image Portability

Finally, when setting Docker environment variables, you should always consider the portability of your images. This means ensuring that your images can run correctly in different environments without requiring specific environment variables to be set.

To achieve this, you can provide default values for your environment variables using the ENV instruction in the Dockerfile. This way, if a specific environment variable is not set when running the container, the default value will be used, ensuring that the container can run correctly.

Related content:

• Python environment variables
• GitHub Actions environment variables

Managing Docker Environment Variables with Configu

Configu is a configuration management platform comprised of two main components:

Configu Orchestrator

As applications become more dynamic and distributed in microservices architectures, configurations are getting more fragmented. They are saved as raw text that is spread across multiple stores, databases, files, git repositories, and third-party tools (a typical company will have five to ten different stores).

The Configu Orchestrator, which is open-source software, is a powerful standalone tool designed to address this challenge by providing configuration orchestration along with Configuration-as-Code (CaC) approach.

Configu Cloud

Configu Cloud is the most innovative store purpose-built for configurations, including environment variables, secrets, and feature flags. It is built based on the Configu configuration-as-code (CaC) approach and can model configurations and wrap them with unique layers, providing collaboration capabilities, visibility into configuration workflows, and security and compliance standardization.

Unlike legacy tools, which treat configurations as unstructured data or key-value pairs, Configu is leading the way with a Configuration-as-Code approach. By modeling configurations, they are treated as first-class citizens in the developers’ code. This makes our solution more robust and reliable and also enables Configu to provide more capabilities, such as visualization, a testing framework, and security abilities.

Learn more about Configu