How to Pass Environment Variable Value into Dockerfile

1. Overview

Environment variables are a convenient way to externalize application configuration; therefore, they’re also useful for building Docker containers. However, passing and using them in the Dockerfile isn’t as easy as it could be.

In this short tutorial, we’ll learn how to pass an environmental variable value into Dockerfile.

First, we’ll demonstrate use cases where passing an environmental variable to a build process might be useful. Then we’ll explain the ARG command we use to accomplish it. Finally, we’ll look at a working example.

2. Environment Variables in Dockerfile vs. Container

Dockerfile is a script containing instructions on how to build a Docker image. Conversely, a Docker container is a runnable instance of an image. Depending on our needs, we may need to have build-time or run-time environment variables.

In this article, we’ll focus only on build-time customization by passing environment variables into our Dockerfile for use with docker build.

3. Advantages of Using Environment Variables in Dockerfile

The biggest advantage of using environment variables is flexibility. We can create just one Dockerfile that will be configured differently depending on the environment that was used to build a container. As an illustration, let’s imagine an application with debug options enabled in the development environment, and the same options disabled in the production environment. With environment variables, we need to create just one Dockerfile that will pass an environment variable holding the debug flag to the container and the app within.

The other important advantage is security issues. Storing passwords or other sensitive information directly in the Dockerfile is probably not the best idea. Environment variables help overcome that problem.

4. Example Configuration

Before we see how to pass environment variable values into a Dockerfile, let’s build an example to test it out.

We’ll create a simple bash script called greetings.sh, which uses an environment variable to print greetings to the console:

#!/bin/sh

echo Hello $env_name

Now we’ll create a Dockerfile in the same directory:

FROM alpine:latest

COPY greetings.sh .

RUN chmod +x /greetings.sh

CMD ["/greetings.sh"]

It copies our script, makes it executable, and runs it. Let’s build the image:

docker build -t baeldung_greetings .

Then we’ll run it:

docker run baeldung_greetings

We should see just one line in the console:

Hello

5. Passing Environment Variables Into a Dockerfile

Dockerfile provides a dedicated variable type ENV to create an environment variable. We can access ENV values during the build, as well as once the container runs.

Let’s see how we can use it to pass a value to our greetings script. There are two different ways to do it.

5.1. Hardcoding Environment Values

The simplest way to pass an environment value is to hardcode it in the Dockerfile. In some cases, this is good enough. Let’s hardcode John as a default name in our Dockerfile:

FROM alpine:latest

ENV env_name John

COPY greetings.sh .

RUN chmod +x /greetings.sh

CMD ["/greetings.sh"]

Now we’ll build and run our image. Here’s the desired console output:

Hello John

5.2. Setting Dynamic Environment Values

Dockerfile doesn’t provide a dynamic tool to set an ENV value during the build process. However, there’s a solution to this problem. We have to use ARG. ARG values don’t work in the same way as ENV, as we can’t access them anymore once the image is built. Let’s see how we can work around this issue:

ARG name
ENV env_name $name

We’ll introduce the name ARG variable. Then we’ll use it to assign a value to the env_name environment variable using ENV.

When we want to set this argument, we’ll pass it with the –build-arg flag:

docker build -t baeldung_greetings --build-arg name=Baeldung .

Now we’ll run our container. We should see:

Hello Baeldung

What if we want to change the name? All we have to do is rebuild the image with a different build-arg value.

6. Conclusion

In this article, we learned how to set environment variables during the build of a Dockerfile.

First, we saw the advantages of parameterizing our Dockerfile. Then we demonstrated how to use the ENV command to set an environment variable, and how to use ARG to allow this value to be modified at build time.

As always, the complete source code of the article is available over on GitHub.