Docker Environment Variable Usage Notes

Environment variables are one of the common methods used to control program behavior during development.

With Docker being increasingly used in development environments in recent years, it is essential to learn how to use environment variables in Docker.

This article introduces several methods of configuring environment variables in Docker and Docker compose.

Requirements #

• Docker 19.03

Dockefile #

Method 1: Pass environment variables into the Docker container using the following command:

$ docker run -e KEY=VALUE <container>

Example:

$ docker run -e DEBUG=1 -e TEST=1 <container>

P.S. If there are multiple variables, you need to use multiple -e parameters.

The second way is to set ENV in Dockerfile:

For example, the following Dockerfile:

FROM busybox
ENV DEBUG=1
ENV TEST=1
CMD ["env"]

The above Dockerfile can be built using the following command:

$ docker build --tag printenv .

Next, use the following command to run the docker container to see if the setting is successful:

$ docker run printenv

If the execution is successful, you will see the following results:

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=3f3704db126f
DEBUG=1
TEST=1
HOME=/root

You can also use the docker inspect command to view ENV settings:

$ docker inspect printenv --format='{{.ContainerConfig.Env}}'

The following is the execution result (you can see the environment variables we just set):

[PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=1 TEST=1]

Or use the following command to see the Env section:

$ docker inspect printenv

The results of the execution.

...(skipped)...
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "DEBUG=1",
                "TEST=1"
            ],
...(skipped)...

Docker-compose #

For the first method, you can use ${environment variable} in the Docker Compose file, which will be automatically substituted when you execute the docker-compose command.

For example:

$ export TAG=1.0

The following is an example of docker-compose.yml . When we run docker-compose up, ${TAG} will automatically be replaced by the value of the environment variable TAG, which is 1.0. In the end, it becomes webapp:1.0:

web:
  image: "webapp:${TAG}"

The second way is to set environment in Docker compose file, for example, the following docker-compose.yml example:

web:
  image: "webapp"
  environment:
    - DEBUG=1
	  - TEST=1

The third one, the .env file.

Add a .env file under the folder where docker-compose.yml file is stored, and docker-compose command will automatically pass in the environment variables.

For example, there are three files in the following folder:

.
├── .env
├── Dockerfile
└── docker-compose.yml

The following are the contents of three example files.

The contents of the Dockerfile file are as follows:

FROM busybox
CMD ["env"]

The contents of the .env file:

TAG=1.0
DEBUG=0
TEST=1

The contents of the docker-compose.yml file are as follows:

version: "3"
services:
  machine:
    build: .
    environment:
      - DEBUG=${DEBUG}
      - TEST=${TEST}

Then, run the following command to see the result:

$ docker-compose up

If the execution is successful, you will see that the environment variables are successfully passed into the container:

Starting t_machine_1 ... done
Attaching to t_machine_1
machine_1  | PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
machine_1  | HOSTNAME=a8287d65d347
machine_1  | DEBUG=0
machine_1  | TEST=1
machine_1  | HOME=/root
t_machine_1 exited with code 0

In addition, it can be observed that the .env file only applies to docker-compose.yml, and TAG=1.0 is not passed into the container. If you want to pass the environment variables in .env into the container,

In addition to the default .env, you can also set env_file to load a specified env file:

version: "3"
services:
  machine:
    build: .
    env_file:
      - machine.env
    environment:
      - DEBUG=${DEBUG}
      - TEST=${TEST}

The priority of environment variables

There are many ways to load environment variables, and there are priorities among them. The following order is provided by the official document:

1. Compose file
2. Shell environment variables
3. Environment file
4. Dockerfile

The earlier the item is, the higher its priority, for example, if the same environment variable is set in both docker-compose.yml and Dockerfile, the setting in docker-compose.yml will take precedence.

References #

Environment variables in Compose | Docker Documentation