Comprehensive Guide to Docker Build Arguments

Docker has revolutionized software development by simplifying how we package, distribute, and deploy applications. One of its most powerful features is the ability to customize the build process using Docker build arguments. These build-time variables provide flexibility and allow developers to tailor their images for specific use cases. In this article, we’ll explore the intricacies of Docker build arguments, their use cases, and best practices for integrating them effectively into your workflows.

---

Understanding Docker Build Arguments

Docker build arguments, or build args, are variables available only during the image build phase. Defined in a Dockerfile using the ARG instruction, they enable developers to create configurable and reusable build scripts. These arguments are passed at build time via the --build-arg flag in the docker build command.

Unlike environment variables (ENV), build args:

• Exist solely during the build process.
• Do not persist in the resulting image.
• Are not accessible within containers running from the image.

Here’s a simple example:

This example allows you to dynamically change the base image version during the build process:

By passing IMAGE_VERSION=latest, the image is built from alpine:latest instead of the default alpine:3.

---

Benefits of Using Docker Build Arguments

Build args provide several advantages that enhance Docker’s flexibility:

1. Customizable Builds:
   • Dynamically adjust configurations, such as selecting specific versions of a base image.
   • Create multiple variations of the same image by tweaking build parameters.
2. Improved Maintainability:
   • Reduce redundancy by consolidating variations into a single Dockerfile.
   • Enable dynamic features without modifying the Dockerfile itself.
3. Scripting Convenience:
   • Integrate with environment variables to avoid hardcoding values in scripts.
   • Simplify CI/CD pipelines by passing build-specific variables.

---

Defining and Using Build Args in Dockerfiles

1. Declaring Build Args: To declare a build arg in a Dockerfile, use the ARG instruction. Optionally, you can provide a default value:

Multiple build args can be defined:

2. Referencing Build Args: Build args can be used in supported instructions like FROM, RUN, LABEL, and ENV:

3. Passing Build Args: Pass values for build args using the --build-arg flag:

If a value isn’t specified, the default value from the Dockerfile is used.

---

Advanced Features and Best Practices

Using Build Args from Shell Variables

To streamline builds, you can pass shell environment variables directly as build args:

This propagates the value of APP_ENV from the shell to the build process.

Making Build Args Mandatory

By default, Docker treats build args as optional. However, you can enforce required input using shell validation within the Dockerfile:

If REQUIRED_ARG is not provided, the build fails with an error.

---

Predefined Build Arguments

Docker provides several built-in build args that require no explicit ARG declaration. These include:

• Proxy settings (HTTP_PROXY, HTTPS_PROXY, etc.).
• Build environment details:
  • BUILDPLATFORM, BUILDOS, BUILDARCH, and BUILDVARIANT for the current build context.
  • TARGETPLATFORM, TARGETOS, TARGETARCH, and TARGETVARIANT for the target platform.

Example usage:

---

Common Use Cases for Build Args

1. Versioning and Tagging:
   • Dynamically set base image tags.
   • Define application versions or build metadata.
2. Feature Toggles:
   • Enable or disable optional components or features at build time.
   • Use build args to populate container environment variables:
   • Default Environment Variables:
4. Default Environment Variables:
5. Platform-Specific Builds:
   • Use predefined build args like TARGETARCH to create architecture-specific images.

---

Limitations of Docker Build Arguments

While build args are a powerful tool, they have some limitations:

1. Scope

Build args are available only after their declaration and are discarded at the end of each build stage. In multi-stage builds, you must redefine build args in every stage where they’re needed:

ARG BUILD_VERSION
FROM alpine AS base
RUN echo ${BUILD_VERSION}

FROM scratch
ARG BUILD_VERSION
RUN echo ${BUILD_VERSION}

     2. Limited Instructions:

• • Build args work only with instructions like FROM, RUN, and LABEL. Unsupported instructions will ignore them.

     3. Not Suitable for Secrets:

• • • Build args are stored in image metadata and can be retrieved using docker history. For secrets, use Docker’s build secrets.

---

Build Args vs. Environment Variables (ARG vs. ENV)

Build args and environment variables serve different purposes:

Aspect	Build Args	Environment Variables
Scope	Build phase only	Runtime inside containers
Persistence	Not saved in the image	Saved in the image and accessible
Usage	Configure build behavior	Configure container behavior

To combine both, assign build arg values to environment variables:

---

Real-World Example: Multi-Stage Build with Build Args

Here’s a practical example of using build args in a multi-stage Dockerfile:

In this setup:

• The NODE_VERSION build arg specifies the Node.js version.
• The build stage compiles the app using the specified Node.js version.
• The production stage uses Nginx to serve the compiled files.

---

Conclusion

Docker build arguments are a powerful tool for creating customizable and reusable Dockerfiles. They simplify dynamic configurations, enable versioning, and improve maintainability. By combining build args with environment variables, developers can ensure flexible and robust builds tailored to diverse needs.

Want to master more Docker techniques? Follow CereBrix for expert insights and practical guides. Stay connected with us on social media at @cerebrixorg!