How do I pass environment variables to Docker containers?

Suppose you are using a MySQL Docker container and you want to pass environment variables to your container while running the container. It's always a good idea to isolate the services from the configuration and it's always advised to use environment variables for this purpose.

Predominantly, there are three different ways through which we can pass environment variables to our Docker containers. These are by using the -e, --env-file, and the ENV instruction inside the Dockerfile. Let's check out all these methods one by one with examples.

Passing Environment Variables Using the --env or -e Flag

To demonstrate this example, let's use the alpine image by pulling it from Docker Hub.

$ docker pull alpine:latest

We can use the --env or its shorthand version -e to pass the environment variables as key-value pairs through the Docker run command. The syntax of the Docker run command is −

$ docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Let's use this syntax to run a container associated with the alpine image and pass our environment variables using the -e flag.

$ docker run -it --name=myalpine --env ENVVARIABLE1=foobar alpine:latest sh

This command uses the -i and -t options to run the container interactively and open the shell. The --name option is used to give a name to the container. The --env option is used to pass the environment variable called ENVVARIABLE1 with a value foobar to the container.

Now you have access to the shell of the container. Inside the shell, execute the env command. This will list all the environment variables of the container.

# env

Using Local Environment Variables

Moreover, if you already have an environment variable in your local machine and you want to pass this environment variable to the container, you can omit the value of the variable.

$ docker run -it --name=myalpine --env VARIABLE2 alpine:latest env

This will directly set the environment variable called VARIABLE2 by taking its value from the local machine.

Using the --env-file Option

If you want to pass a limited number of environment variables to the container, you can use the previous method. However, if the number of the environment variables to be passed is large, you can store the variables in a text file in key-value format and pass the name of this file using the --env-file option in the Docker run command. It will automatically read and import these variables from the mentioned file.

Create a file called env.txt with the following content.

ENV1=VALUE1
ENV2=VALUE2
ENV3=VALUE3

Now, you can use the following command to create a container called myalpine and pass the environment variables from this file using the --env-file option.

$ docker run -it --name=myalpine --env-file env.txt alpine:latest env

Note: The file must exist in the same path where you are executing this command in your local machine. If not, mention the full path of the file. This command will list all the environment variables in the container and you will find the ones mentioned in the env.txt file as well.

Using the ENV Dockerfile Instruction

If you are trying to build an image using the Dockerfile, you can pass the environment variables using the ENV instruction. The syntax of this instruction is −

ENV <key>=<value> ...

The values that you pass will be the environment variables for all the subsequent instructions in your Dockerfile. Examples are −

ENV MY_NAME="Jane Anniston"
ENV MY_PET=The\ Dog
ENV MY_CAT=TOMMY

Similar to command line parsing, you will have to escape quotes and spaces using backslashes. All the environment variables will persist throughout the container lifecycle. If you want to pass only a single environment variable with one ENV instruction, you can also omit the equal operator.

Comparison of Methods

Security Best Practices

When working with environment variables in Docker containers, avoid passing sensitive information such as passwords, API keys, or passphrases directly. Instead, consider using Docker secrets or external secret management solutions. Environment variables can be visible in process lists and Docker inspect commands, potentially leading to security vulnerabilities.

Conclusion

Docker provides three main methods to pass environment variables to containers: the -e/--env flag for individual variables, --env-file for bulk variables from files, and the ENV instruction in Dockerfiles for build-time defaults. Choose the method based on your specific requirements, keeping security considerations in mind when handling sensitive data.