We often see the applications configured to read the additional configuration via the environment variables. In the case of non-containerized applications, we can modify the configuration and restart the application to use the updated configuration. However, restarting the application to use the updated configuration does not work with containerized applications due to immutable images and ephemeral containers.
This tutorial will discuss how to overcome this limitation by passing the environment variables to the Docker containers.
1. Pass Environment Variables From the Command Line
Docker allows us to pass the environment variables to the container from the command line using the container run child command. It allows us to set new environment variables as well as overwrite the existing environment variables.
1.1. Passing a Variable Name and Value
Let’s use the -e option of the container run child command to pass an environment variable in a key=value format:
$ docker container run -e app="demo-app" -it -d --name web-server-01 nginx:alpine1.2. Passing Only Variable Name
In the earlier example, we used the key=value pair syntax with the command. However, we can leave out the value part if the variable is already present in the current shell. Let’s understand this with an example.
First, create an environment variable in the current shell:
$ export web_server_name="nginx"
$ echo $web_server_name
nginxNow, let’s create a new container and pass the environment variable web_server_name to it:
$ docker container run -e web_server_name -it -d --name web-server-02 nginx:alpine1.3. Passing Multiple Variables
Docker allows us to pass multiple environment variables at once. We can achieve this using the -e option multiple times with the same command.
In the following example, we are using a combination of key=value and just key syntax to pass the environment variables.
$ docker container run -e app="demo-app" -e web_server_name -it -d --name web-server-03 nginx:alpine1.4. Verifying Variables
Use the exec command in the web-server-01 container and check the value of the environment variables using the printenv command.
# Verify single variable
$ docker container exec -it web-server-01 printenv | grep "app"
app=demo-app
# Verify multiple variables
$ docker container exec -it web-server-03 printenv | grep -E "app|web_server_name"
app=demo-app
web_server_name=nginx2. Pass Environment Variables Using External Files
2.1. Benefits of Using External File
There is a downside to the previous approach of using the command line. By default, the shell stores the history of all the commands.
Using the bash’s built-in history command, we can view the previously executed command. For example, the below command lists the commands that we used earlier to create the containers:
$ history | grep -E "web-server-0?"This might cause security risks if we use sensitive information with the command, such as usernames and/or passwords.
To overcome this limitation, we can pass environment variables using the external file. We can achieve this using the –env-file option. There are several advantages of this approach, such as:
- It allows us to control the access of the file using the appropriate permissions. For instance, we can do this using the chmod and chown commands.
- It allows us to make the configuration more readable by adding comments and newlines to it. In Docker, we can use the pound(#) character for comments.
- It allows us to create multiple configuration files and use them in different environments without rebuilding the images.
- It provides an additional security layer, as the history command doesn’t record the contents of these files.
2.2. Creating an Environment Variable File
First, create a file docker-variables.env with the environment variables. It is important to note that, the environment variables file should use the key=value syntax.
$ cat docker-variables.env
# Application name
app=demo-app
# Web server used by the application
web_server_name="nginx"However, we can just use the variable name if the variable is available in the current shell.
app=demo-app
# This variable is define in the shell
web_server_name2.3. Passing Variable File from Command Line
Next, create a container and pass the environment variables file using –env-file argument.
$ docker container run --env-file docker-variables.env -it -d --name web-server-04 nginx:alpine2.4. Passing Multiple Files
In addition to this, we can pass environment variables from multiple files. In that case, we can the –env-file option multiple times with the same command.
$ docker container run --env-file docker-variables-1.env --env-file docker-variables-2.env -it -d --name web-server-05 nginx:alpine3. Pass Environment Variables Using Docker Compose
We can use Docker’s compose tool to create multi-container applications. It allows us to run and manage multiple containers at once in an effective way. Similar to the run child command we can pass environment variables to the container using the docker-compose command.
3.1. Variables with Static Values
Let’s define a container configuration in a YAML file and define environment variables under the environment section. It is important to note that whitespace must not be on either side of the equal to sign.
$ cat docker-compose.yaml
...
environment:
- app=demo-app
- web_server_name=nginxWe can also specify the environment variables using the map syntax. This syntax uses a colon(:) to separate key-value pairs.
$ cat docker-compose.yaml
...
environment:
app: demo-app
web_server_name: nginxStart the container and exec into the web-server-06 container and print the value of the environment variables:
$ docker container exec -it web-server-06 printenv | grep -E "app|web_server_name"
app=demo-app
web_server_name=nginx3.2. Variables with Dynamic Values
Docker Compose allows us to pass environment variables dynamically. We can access those variables in the compose file using the ${VARIABLE_NAME} notation.
Let’s modify the environment section of the compose file to pass variables using the dynamic notation:
$ cat docker-compose.yaml
...
environment:
- app=${APP}
- web_server_name=${WEB_SERVER_NAME}There are two ways to pass the environment variables dynamically.
- By exporting to the current shell
- By passing the value when starting the container
$ export APP="demo-app" #first way
$ WEB_SERVER_NAME=nginx docker-compose up -d #second wayIt is important to note that the second method’s variable’s scope is limited to that command only. Shell destroys this variable after the execution of the command.
3.3. Using External File When Variables are Large in Number
In the previous examples, we used the environment section of the compose file to pass the environment variables. However, that approach is more suitable only when the variables are small in numbers. The length of the compose file increases significantly over the period of time as we introduce more and more variables.
To mitigate this situation, we can move all the environment variables to the external file. Then compose can use this file to pass environment variables to the container.
$ cat docker-compose.yaml
...
container_name: web-server-06
env_file: compose-variables.envWe can also pass environment variables using multiple files. In that case, the env_files section accepts multiple files using the YAML array syntax.
$ cat docker-compose.yaml
...
container_name: web-server-06
env_file:
- compose-variables-1.env
- compose-variables-2.env4. Conclusion
This article discussed how to pass environment variables to the Docker container. First, we discussed how to pass them using the command line argument and an external file. Finally, we discussed how to use Docker Compose for the same purpose.
Happy Learning !!
Comments