Docker - ADD, Update, Export Environment variable

When writing a Dockerfile or docker-compose.yml you often need to rely on the ENVIRONMENT variable and there could be many reasons behind it, for example -

  1. If your container is using Python then you might wanna rely on the Python version which is set into the host machine's environment variable.
  2. another use case could be JAVA_HOME - If your container needs Java for runtime then you might wanna use existing environment variable JAVA_HOME which is being already set into the host machine's environment variable.

In this blog post, we will go through various examples on - "How do I set an environment variable in Docker?", "How to access environment variable in Docker?", "How do I pass an environment variable in Docker run command?"

Table of Content

  1. How to use the Environment variable inside docker-compose.yml file?
  2. How to set the Environment variable in the container?
  3. What is the docker environment file(.env) file and how to use the docker environment file(.env) file?
  4. How to set an environment variable in a running docker container?
  5. Is it possible to overwrite the environment variable in a running container?


1. How to use Environment variable inside docker-compose.yml or Dockerfile file?

To use Environment variable inside your docker-compose.yml or Dockerfile you must use either of the following syntax -

1${YOUR_ENVIRONMENT_VARIABLE_NAME}  or $YOUR_ENVIRONMENT_VARIABLE_NAME

Here is an Example of docker-compose.yml in which I am trying to use JAVA_HOME environment variable to define my docker image name .e.g. image: jhooq-spring-boot-${JAVA_HOME}:1-

 1version: '3'
 2
 3services:
 4  jhooq-springboot-container:
 5    image: jhooq-spring-boot-${JAVA_HOME}:1
 6    build:
 7      context: ./
 8      dockerfile: Dockerfile
 9    volumes:
10      - /data/jhooq-springboot-container
11    ports:
12      - "8080-8100:8080" 

So when you run the docker-compose command the expression image: jhooq-spring-boot-${JAVA_HOME}:1 will be evaluated based on the Java installed onto the host machine. Let's say if you have installed JDK 1.8 then the image name would be jhooq-spring-boot-1.8

What if you are missing the environment variable?

In case if you have SET the environment variable then docker-compose command will not fail but instead, it will substitute with an empty string and the docker image name would look like this - jhooq-spring-boot



2. How to set the Environment variable in the container?

To set an environment variable you should use flag -e while using docker run or docker-compose command.

Here are the example of both the commands -

1docker run -e PYTHON_VERSION=3.8 
1docker-compose -e PYTHON_VERSION=3.8 

But always keeps in mind that you can override the environment variables with your own custom value but still there is an order of precedence with top is being the highest propriety -

  1. Compose file - Any environment set in docker-compose.yml will get higher precedence
  2. Shell environment variables - If you set environment variable via command line then it will get the precedence but will still come after Compose File
  3. Environment file - If the environment variable is not overridden by docker-compose.yml, shell environment the variable then the environment file will get the precedence.
  4. Dockerfile - If all neither docker-compose.yml, shell environment nor environment file has overridden the variable then Dockerfile will take the preference.
  5. Variable is not defined - Finally if the variable is not found in all previous options then you will be thrown with variable not found message.


3. What is docker environment file(.env) file and how to use docker environment file(.env) file?

When building complex dockerfile or docker-compose.yml for managing your docker containers then use of docker environment file(.env) file is always recommended because it will give you better control over the environment variable which you need during the build and run phase of your docker container.

3.1 Benefits of using docker environment file(.env) file

  1. Define and Override - The key advantage of using docker environment file(.env) file is you do not have to rely on the environment variables of the host machine you can simply define as well as override the environment variables.

  2. Re-usability - Once you define environment variable inside docker environment file(.env) file, it can be reused by other containers also.

For Example - If you have two docker-compose.yml files and each docker-compose need to fetch the environment variable PYTHON_VERSION. So you can define the environment variable PYTHON_VERSION inside the .env file and it can be accessed by all the containers.



3.2 How to create and where to save the docker environment file(.env) file?

How to create .env file? - The .env file creation is very simple, just open an editor and save the file with .env extension.

(*Note - You do not have to assign any name to file just make sure to save it with .env extension)

Where to save? - After creating the .env file you simply need to save the file in any directory of your choice. But to use the .env file you have to specify the path during the docker run command.

Here is the screenshot of my directory structure -

Docker environment file .env

Considering the above directory structure, if I want to run the docker-compose.yml file present in spring-boot the directory then I am gonna use the following docker run command -

1docker run --env-file /docker-project/environment/.env jhooq-spring-boot-image

Similarly, if you wanna run the docker-compose.yml file present in python directory using the same environment file -

1docker run --env-file /docker-project/environment/.env jhooq-spring-boot-image


4. How to set an environment variable in a running docker container?

In the previous points we have discussed setting environment variables before starting the docker container but - what if you want to set the environment variable in an existing running docker container?

It's a bit tricky but you can certainly do it using the following docker command but remember to replace the CONTAINER_ID -

1docker exec -i <YOUR_RUNNING_COTAINER_ID> /bin/bash -c "export MY_VARIABLE=value && export MY_VARIABLE=value && 
2run_cmd" 

4.1 Docker container service using Swarm

If you are running your container as Service using the Docker Swarm then you can use the following docker command to update your desired environment variable -

1docker service update --env-add MY_VARIABLE=value <YOUR_SERVICE_NAME> 

(*Note - Remember to replace your service name)


5. Is it possible to overwrite the environment variable in a running container?

The answer is NO, it is not possible to overwrite an environment variable in a running container because once your start a docker container then docker starts many other services behind the scene such as -

  1. Volume
  2. Mounts
  3. Network configuration

Think for a second you started a docker container and docker container has started the above-mentioned services in the background based on the environment variable which you have passed at the time of creation.

So if you are planning to overwrite a variable then docker is unable to update those services. To make a change in an existing environment variable in a running docker container you have to delete and recreate docker container.

Read More - On GitHub: How to set an environment variable on an existing container?

Posts in this Series