Generic Top

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE

1. Overview

Environment variables are a convenient way to externalize application configuration. Therefore they are also useful for building Docker containers. However, passing and using them in the Dockerfile is not as easy as it might be.

In this short tutorial, we'll take a closer look at how to pass an environmental variable value into Dockerfile.

First, we'll show possible use cases when passing an environmental variable to a build process might be usefulThen, we'll explain the ARG command that does it. Finally, we'll see a working example.

2. Environment Variables in Dockerfile vs. Container

Dockerfile is a script containing instructions on how to build a Docker image. On the other hand, 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.

We're focusing 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 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, that uses an environment variable to print greetings to console:

#!/bin/sh

echo Hello $env_name

Now, let's 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, let's 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 value to our greetings script. There are two different ways to do it.

5.1. Hardcoding Environment Values

The simplest way to pass environment value is to hardcode it in the Dockerfile. This can be good enough in some cases. 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, let's build and run our image. Here's the desired console output:

Hello John

5.2. Setting Dynamic Environment Values

Dockerfile does not provide a dynamic tool to set ENV value during the build process. However, there is a solution to this problem. We have to use ARG. ARG values do not 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're introducing the name ARG variable. After that, we're using it to assign a value to the env_name environment variable using ENV.

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

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

Now, let's run our container. We should see:

Hello Baeldung

What if we want to change the name? All we have to do is just 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 saw 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.

Generic bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

>> CHECK OUT THE COURSE
Generic footer banner
Comments are closed on this article!