When we create a Docker container, sometimes, we have the need of passing “arguments” to it, typically, port numbers for services, or some paths.
For this, we configure the environment variables of the container, and that’s what this example is going to show.
For this example, Linux Mint 18 and Docker version 1.12.1 have been used.
You may skip Docker installation and jump directly to the beginning of the example below.
1. Installation
Note: Docker requires a 64-bit system with a kernel version equal or higher to 3.10.
We can install Docker simply via apt-get, without the need of adding any repository, just installing the docker.io package:
sudo apt-get update sudo apt-get install docker.io
For more details, you can follow the Install Docker on Ubuntu Tutorial.
2. What are environment variables?
When we talk about environment variables in Docker context, we are talking about the variables that we pass to a container, that will be set in its environment. Pretty easy, as you can see.
Let’s see a practical case, executing the env command inside a container. In my case, is a container named busybox1, based on a Busybox image, that we have created just running:
docker run -i -t -d --name=busybox1 busybox
(The -i, -t and -d options are for keeping the container alive, detached).
Now, we can execute the env command:
docker exec busybox1 env
Receiving the following output:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=0fd687d954b0 TERM=xterm HOME=/root
Showing the list of the environment variables set in our container.
Note that the concept is exactly the same than in Linux, but applied in Docker context. Now we will see how to deal with environment variables in Docker containers.
3. Setting environment variables
Is essential to understand that the environment variables are set in container instantiation, that is, when we execute the run command.
For this, we have to use the -e (--env) option. The format is the following:
docker run -e <variable1>='<value1>' [-e <variableN>='<valueN>'] <image>
There are a couple of things that we have to take into account:
- We have to pass the
-efor each variable. - The quotes for the value are only required for values including whitespaces, but it’s always good to follow the same convention, adding them always.
Let’s see an example, creating the container and executing the env command (inside the container; not a Docker command), and seeing the output:
docker run -e variable1='value1' -e variable2='value2' busybox env
The shown output is:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=b7ab4a51b363 variable1=value1 variable2=value2 HOME=/root
3.1. Reading environment variables from a file
Docker gives the chance of reading the environment variables from a file, which is especially useful when we have a large list of variables and we want to reuse them.
The format this file has to follow is very simple, it’s just about setting a var=val in different lines, for example:
env.list
variable1=value1 variable2=value2
This file does not have to have any specific naming; we can set the name and extension we want.
Also, note that we shouldn’t use quotes if we use a environment variable list file: if we use them, the quotes will be part of the value itself.
For specifying this file when instantiating the image, we have to use the env-file option:
docker run --env-file=<path/to/file> <image>
For example:
docker run --env-file=./env.list busybox env
If we execute the command shown above, we will see that the printed environment variable list is the same as in previous occasions, but now being defined in a file.
We can also combine the usage of the file, and the specification of the variables inline:
docker run --env-file=./env.list -e variable3=value3 busybox env
Showing:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=0e0361c22eae variable1=value1 variable2=value2 variable3=value3 HOME=/root
Of course, we have to be cautious with the redefinitions: if a variable is defined in both file and inline, the one defined inline will have precedence. This means that, for the previous env.list, if we also define the following inline variable:
docker run --env-file=./env.list -e variable2=value3 busybox env
The value set in the container for variable2 will be value3, instead of value2.
4. Environment variables in Dockerfiles
Of course, we can set environmental variables in our Dockerfiles. For this, we have to use the ENV instruction.
There are several ways for using this instruction:
# Without equality sign, specifying the 'ENV' instruction in each line
ENV variable1 value1
ENV variable2 value2
# With the equality sign, without the need of specifying 'ENV' for every assignment, but using '\'
ENV variable1=value1\
variable2=value2As for inline variables, we have to use quotes for values containing whitespaces.
So a simple Dockerfile for doing what we have done in the previous sections could be:
Dockerfile
FROM busybox ENV variable1=value1\ variable2=value2
Then, we build the image from this Dockerfile:
docker build --tag=mybusybox . # The path to my Dockerfile
And run it, showing the environment variables:
docker run mybusybox env
And we will see the expected output:
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOSTNAME=d677d9eac45b variable1=value1 variable2=value2 HOME=/root
5. Summary
In this tutorial, we have seen how to set environment variables of containers at instantiation time, as a method of passing arguments to them. We have started with the most basic solution, that consists on passing the arguments inline one by one; and then how to define them in a file, which can be more comfortable for some situations; and, also, for our own Dockerfiles.
