How to Set Docker Environment Variables

Introduction

Docker supports environment variables as a practical way of externalizing a containerized app configuration. When included in a Docker image, environment variables become available to app containers created based on the image.

This article shows you how to set Docker environment variables when creating Docker images. It also provides instructions for overriding the default variable values in existing images.

Prerequisites

• Docker installed (Read our installation manuals for Ubuntu, CentOS, and Rocky Linux).
• Administrative access to the system or non-root access to Docker enabled.

Types of Docker Environment Variables

A Dockerfile, a script containing instructions for image creation, supports two environment variable types:

• ARG variables usually store important high-level configuration parameters, such as the version of the OS or a library. They are build-time variables, i.e., their only purpose is to assist in building a Docker image. Containers do not inherit ARG variables from images. However, users can later retrieve ARG values from an image with the docker history command.
• ENV variables store values such as secrets, API keys, and database URLs. Unlike ARGs, they persist inside the image and the containers created from that template. Users can override ENV values in the command line or provide new values in an ENV file.

How to Set Docker Environment Variables?

Both ARG and ENV variables are defined in the Dockerfile. The following sections describe how to define variables and assign them default and modified values.

Set ARG Values

A Dockerfile can contain just the ARG variable definition or the definition and the variable's default value. When users apply a Dockerfile configuration with the docker build command, they have the option to introduce or modify the value using command-line options.

Follow the steps below to create an ARG variable in Docker:

1. Create a directory for the new Docker image and cd into the path.

mkdir [directory-path] && cd [directory-path]

2. Create a Dockerfile using a text editor. We will be using nano.

nano Dockerfile

3. In the Dockerfile, use the following syntax to define an ARG variable:

ARG [variable-name]

Optionally, assign a default value to the variable by typing:

ARG [variable-name]=[default-value]

For example, to define a variable named TEST1 with the value value1, type:

ARG TEST1=value1

Add the following line to the file for testing purposes.

RUN echo "The ARG variable value is $TEST1"

Save the file and exit.

4. Execute docker build to create an image. The -t option lets you name the image.

docker build -t [image-name] .

The command output shows Docker going through the Dockerfile and performing the instructions. Step 3 of the procedure executes the test command, which confirms that Docker successfully assigned the value to the variable.

Modify ARG Value with docker build

If you did not provide a value for the ARG variable or want to modify the default value while building the image, use the --build-arg option.

docker build -t [image-name] --build-arg [arg-variable]=[value] .

The example below replaces value1 of the TEST1 variable with new_value.

docker build -t test_image1 --build-arg TEST1=new_value .

Set ENV Values

Similar to ARG variables, the statement that defines ENV variables in Dockerfile provides the variable's definition and an optional default value. Users can provide values later via the command line or Docker Compose.

Follow the steps below to create an ENV variable:

1. Create a directory for the new Docker image and cd into it.:

mkdir [directory-path] && cd [directory-path]

2. Create a new Dockerfile in a text editor.

nano Dockerfile

3. Define a variable and (optionally) assign it a default value by typing:

ENV [variable-name]=[default-value]

For example, to create the TEST2 ENV variable with the default value of value2, type:

ENV TEST2=value2

Below is an example Dockerfile containing one ARG and one ENV variable.

To test the procedure, add a line that prints the variable values in the output:

RUN echo "The ARG variable value is $TEST1, the ENV variable value is $TEST2"

Save the file and exit.

4. Build a new Docker image by typing:

docker build -t [image-name] .

The output confirms that the ENV variable was set successfully.

While the ARG variable is unavailable after the image-building process, ENV persists in the containers. To test this property, use docker run to create a container using the image created in this step.

docker run --name [container-name] -d [test-image]:latest

The command outputs the container ID for the new container.

Inspect the container by typing:

docker container inspect [container-name-or-id]

The Config section of the output contains a list of environment variables in the container. The example below shows that the ENV variable persisted while the ARG variable no longer exists.

Set ENV Value via Command Line

The --build-arg option serves to modify ARG values. To use the option with ENV variables:

1. In a Dockerfile, assign the name of the ARG variable as the value of ENV:

ARG TEST1
ENV TEST2=$TEST1

Add the following command to test this feature:

RUN echo "The ENV variable value is $TEST2"

2. Build the image. Use the --build-arg option to pass a value to ARG:

docker build --build-arg [arg-variable]=[value] .

The output shows that Docker processed the ARG value and assigned it to ENV.

How to Override Docker Environment Variables

Users override ENV variable defaults defined in the Dockerfile in multiple ways. In order of precedence, the application considers the values set by:

• The containerized application itself.
• The -e command-line argument of the docker run command.
• The .env file provided through the docker run --env-file option.
• The Dockerfile.

Overriding Single ENV Variable via Command Line

Use the -e option with docker run to override a single defined ENV variable when creating a container.

docker run --name [container-name] -e "[variable-name]=[new-value]" [image-name]

The example below changes the value of TEST2 to runtime_value while creating the test_container1 from test_image3:

docker run --name test_container1 -e "TEST2=runtime_value" test_image3

With Docker Compose, place the value you wish to override in the environment section of the file:

version: '[version-number]'

services:
  [service-name]:
    image: [image-name]
      environment:
        - env_var_name=[new-value]

The new value appears when inspecting test_container1:

docker container inspect test_container1

Overriding Multiple ENV Variables with ENV File

Provide a set of variable values on runtime by creating an ENV file that contains the relevant key-value pairs.

1. Create the file with a text editor:

nano [env-filename]

2. Populate the file with key-value pairs:

[variable1-name]=[value1]
[variable2-name]=[value2]
[variable3-name]=[value3]
...

Save the file and exit.

3. Pass the values from the file with the --env-file option.

docker run --name [container-name] --env-file [path-to-env-file] [image-name]

If you are using Docker Compose, use the env_file field to reference the ENV file:

version: '[version-number]'

services:
  [service-name]:
    image: [image-name]
    env_file: [env-file-path]

Conclusion

After reading this tutorial, you should know how to define and set ARG and ENV environmental variables in a Dockerfile and how to override their values using Docker CLI and Docker Compose.

Next, learn how to mount NFS Docker volumes.