Understanding Docker Build ARG: A Comprehensive Guide

Docker has revolutionized the way developers build, ship, and run applications. One of its less-discussed but highly powerful features is the ARG instruction, which enables passing build-time variables to Docker images. In this blog, we’ll explore what ARG is, why it’s essential, when to use it, and how it differs from ENV variables. We’ll also include practical examples to help you get started.

What is a Docker Build ARG?

ARG is a Dockerfile instruction that defines a variable you can pass to your build process using the --build-arg flag. Unlike ENV, which is available both at build-time and run-time, ARG variables are only accessible during the image build process.

Why Do We Need Docker Build ARG?

Here are some common use cases for ARG:

1. Customization at Build Time: ARG allows you to pass different configurations to your Docker image without hardcoding values in the Dockerfile. This is useful for tailoring builds for specific environments, such as development, staging, or production.

2. Securely Passing Sensitive Data: While not ideal for sensitive data (more on this later), ARG can be used for build-time secrets like API keys or tokens that don’t need to persist in the final image.

3. Dynamic Dependency Management: You can control dependencies dynamically, such as installing different versions of a tool based on the build argument.

How to Use Docker Build ARG

Here’s a step-by-step example:

Example Dockerfile:

# Define a build-time argument
ARG BASE_IMAGE=alpine:3.18

# Use the argument in subsequent instructions
FROM ${BASE_IMAGE}

# Define another argument
ARG APP_NAME=myapp

# Use the argument during build
RUN echo "Building $APP_NAME..."

# Define an environment variable for runtime
ENV APP_ENV=production

CMD ["sh"]

Building the Image:

You can pass values to ARG using the --build-arg flag:

docker build --build-arg BASE_IMAGE=ubuntu:22.04 --build-arg APP_NAME=awesomeapp -t custom-image .

Output:

Building awesomeapp...

When Should You Use Docker Build ARG?

1. Environment-Specific Builds: To create images tailored for specific environments without duplicating Dockerfiles.

2. Customizing Base Images: When you want to build on different operating systems or distributions.

3. Passing Non-Sensitive Configuration Values: Such as version numbers, flags, or feature toggles.

4. Automating Builds: When integrating with CI/CD pipelines for dynamic configurations.

Docker Build ARG Limitations

Build args have a few limitations to bear in mind:

1. Scope of Usage: Build args can only be used by the Dockerfile instructions that follow their definition. If you try to access a build arg before it’s defined, an empty string will always be returned:

   # prints nothing
   RUN echo ${foo}
   
   ARG foo=bar
   
   # prints bar
   RUN echo ${foo}

2. Multi-Stage Builds: Build args are discarded at the end of each build stage. When writing a multi-stage Dockerfile, you must include the ARG instruction in every stage that needs a particular build arg:

   FROM node:latest AS node
   
   RUN npm install
   ARG BUILD_VERSION
   RUN echo $BUILD_VERSION > version.txt
   
   FROM httpd:alpine AS httpd
   
   ARG BUILD_VERSION
   RUN echo $BUILD_VERSION > version.txt

   If the second ARG instruction were removed from this Dockerfile, the final RUN statement wouldn’t have the expected result. The first ARG instruction only applies to the stage it’s defined in. This differs from the behavior of ENV instructions.

3. Instruction Support: Build args can only be referenced by Dockerfile instructions that support variable interpolation. These are:

   • ADD

   • COPY

   • ENV

   • EXPOSE

   • FROM

   • LABEL

   • STOPSIGNAL

   • USER

   • VOLUME

   • WORKDIR

   • ONBUILD

   Build arg references won’t be expanded when used in any other instruction.

Docker ARG vs. Docker ENV

While both ARG and ENV manage variables in Docker, they serve distinct purposes:

Example:

Dockerfile:

# Define ARG and ENV
ARG VERSION=1.0
ENV APP_ENV=development

# Use ARG and ENV
RUN echo "Building version $VERSION"
RUN echo "Runtime environment: $APP_ENV"

CMD ["sh"]

Building:

docker build --build-arg VERSION=2.0 -t example-image .

Running:

docker run -e APP_ENV=production example-image

Output:

• During Build: Building version 2.0

• During Runtime: Runtime environment: production

Key Considerations

1. Sensitive Data: Avoid using ARG or ENV for sensitive data like secrets or passwords. Use Docker’s secrets management or external tools like HashiCorp Vault.

2. Build Cache: Changing ARG values invalidates the build cache for instructions that follow the ARG declaration.

3. Layering Impact: Be cautious about where you place ARG and ENV instructions in your Dockerfile to optimize caching and image layering.

Conclusion

Docker’s ARG instruction is a versatile tool for customizing image builds. By understanding the differences between ARG and ENV, you can effectively manage both build-time and runtime configurations, making your images more flexible and maintainable. With these tips and examples, you’re now ready to leverage the full power of Docker build arguments in your projects.

Happy Dockerizing!