Wie man das Problem "docker buildx build requires exactly 1 argument" löst

Introduction

Docker Buildx extends the standard Docker build command with enhanced features for creating multi-architecture images. However, users often encounter the "docker buildx build requires exactly 1 argument" error when working with this tool. This comprehensive tutorial will guide you through understanding Docker Buildx, diagnosing this common error, and implementing effective solutions.

By the end of this lab, you will have hands-on experience setting up Docker Buildx, creating Docker images, troubleshooting the "requires exactly 1 argument" error, and building images for multiple architectures. These skills are essential for modern containerized application development and deployment.

Skills Graph

Setting Up Docker Buildx

Docker Buildx comes pre-installed with Docker but needs to be properly set up before use. In this step, we will verify Docker is installed, enable Docker Buildx, and create our first builder instance.

Verifying Docker Installation

Let's first confirm that Docker is installed and running on our system:

docker --version

You should see output similar to:

Docker version 20.10.21, build baeda1f

This confirms that Docker is installed and ready to use.

Understanding Docker Buildx

Docker Buildx is a CLI plugin that extends Docker's functionality with BuildKit. It enables:

• Building images for multiple platforms (like AMD64, ARM64) simultaneously
• More efficient layer caching
• Improved build performance
• Advanced build features

Creating a Docker Buildx Builder

Let's create and use a new Docker Buildx builder:

docker buildx create --name mybuilder --use

The output should look similar to:

mybuilder

Now let's verify that our builder was created and is set as the default:

docker buildx ls

You should see output similar to:

NAME/NODE    DRIVER/ENDPOINT             STATUS  PLATFORMS
mybuilder *  docker-container
  mybuilder0 unix:///var/run/docker.sock inactive
default      docker
  default    default                     running  linux/amd64, linux/386

The asterisk (*) next to mybuilder indicates it's the currently active builder.

Inspecting the Builder

Let's examine the details of our builder:

docker buildx inspect mybuilder

This will show you the builder's configuration, including supported platforms and its current status.

Now that we have successfully set up Docker Buildx, we're ready to move on to creating a Dockerfile to use with our builder.

Creating a Simple Dockerfile for Testing

Before using Docker Buildx for building images, we need to create a simple Dockerfile. This will serve as our test case for understanding the "requires exactly 1 argument" error.

Understanding Dockerfiles

A Dockerfile is a text document containing instructions to build a Docker image. It automates the process of creating containers with specific configurations.

Let's create a directory for our project:

mkdir -p ~/project/buildx-test
cd ~/project/buildx-test

Creating a Basic Dockerfile

Now, let's create a simple Dockerfile using the nano text editor:

nano Dockerfile

Copy and paste the following content into the Dockerfile:

FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
  curl \
  nginx \
  && rm -rf /var/lib/apt/lists/*

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Press Ctrl+O followed by Enter to save, then Ctrl+X to exit nano.

Let's break down this Dockerfile:

• FROM ubuntu:22.04 - Uses Ubuntu 22.04 as the base image
• RUN apt-get update... - Updates package lists and installs curl and nginx
• EXPOSE 80 - Indicates that the container will listen on port 80
• CMD ["nginx", "-g", "daemon off;"] - Runs nginx in the foreground when the container starts

Creating a .dockerignore File

A .dockerignore file helps to exclude files and directories that are not needed in the build context, making builds faster and more efficient:

nano .dockerignore

Add the following content:

.git
.gitignore
*.md

Press Ctrl+O followed by Enter to save, then Ctrl+X to exit nano.

Verifying the Project Structure

Let's check that our files are created correctly:

ls -la

You should see output similar to:

total 16
drwxrwxr-x 2 labex labex 4096 Jan 1 00:00 .
drwxr-xr-x 3 labex labex 4096 Jan 1 00:00 ..
-rw-rw-r-- 1 labex labex   21 Jan 1 00:00 .dockerignore
-rw-rw-r-- 1 labex labex  159 Jan 1 00:00 Dockerfile

Now that we have a basic Dockerfile, we're ready to test Docker Buildx and explore the "requires exactly 1 argument" error in the next step.

Understanding and Resolving the "Requires Exactly 1 Argument" Error

In this step, we'll deliberately trigger the "requires exactly 1 argument" error to understand its causes, then learn how to resolve it.

Triggering the Error

First, let's navigate to our project directory if we're not already there:

cd ~/project/buildx-test

Now, let's try to build an image using Docker Buildx without specifying the build context:

docker buildx build

You should see an error message similar to:

"docker buildx build" requires exactly 1 argument.
See 'docker buildx build --help'.

Usage:  docker buildx build [OPTIONS] PATH | URL | -

This error occurs because the docker buildx build command requires a build context (the directory containing the Dockerfile) as an argument.

Understanding the Error

The "requires exactly 1 argument" error means that Docker Buildx needs to know where to find the files needed for building the image. This argument is typically a path to the directory containing your Dockerfile (the build context).

Common scenarios that trigger this error include:

1. Forgetting to specify the build context
2. Using incorrect command syntax
3. Placing options in the wrong order

Correcting the Error

Let's fix the command by adding the build context. The simplest way is to use . to indicate the current directory:

docker buildx build .

This time, Docker will start the build process, but we'll notice it doesn't tag the image, making it difficult to reference later.

Let's stop the build with Ctrl+C if it's still running, and try again with a proper tag:

docker buildx build -t nginx-test:latest .

You should see output showing the build progress:

[+] Building 12.8s (7/7) FINISHED
 => [internal] load build definition from Dockerfile                          0.0s
 => => transferring dockerfile: 203B                                          0.0s
 => [internal] load .dockerignore                                             0.0s
 => => transferring context: 34B                                              0.0s
 => [internal] load metadata for docker.io/library/ubuntu:22.04               0.5s
 => [1/3] FROM docker.io/library/ubuntu:22.04@sha256:...                      0.0s
 => CACHED [2/3] RUN apt-get update && apt-get install -y     curl     nginx  0.0s
 => CACHED [3/3] EXPOSE 80                                                    0.0s
 => exporting to image                                                        0.0s
 => => exporting layers                                                       0.0s
 => => writing image sha256:...                                               0.0s
 => => naming to docker.io/library/nginx-test:latest                          0.0s

Using Different Buildx Options

Let's explore some additional options with Docker Buildx:

1. Building and loading the image into Docker's local image store:

docker buildx build --load -t nginx-test:local .

2. Building without using the build cache (forcing a fresh build):

docker buildx build --no-cache -t nginx-test:nocache .

3. Building and outputting only the final image ID:

docker buildx build -q -t nginx-test:quiet .

Verifying the Built Images

Let's check the images we've built:

docker images | grep nginx-test

You should see output similar to:

nginx-test     quiet      abcdef123456   5 minutes ago   123MB
nginx-test     nocache    fedcba654321   5 minutes ago   123MB
nginx-test     local      123456abcdef   5 minutes ago   123MB
nginx-test     latest     abcdef123456   5 minutes ago   123MB

Now you understand the common "requires exactly 1 argument" error with Docker Buildx and know how to properly build images with various options.

Building Multi-Architecture Images with Docker Buildx

One of the most powerful features of Docker Buildx is its ability to build images for multiple architectures simultaneously. In this step, we'll learn how to create multi-architecture images.

Understanding Multi-Architecture Images

Multi-architecture images allow the same image name to work on different platforms (like AMD64, ARM64, etc.). Docker automatically selects the appropriate version for the host architecture when the image is pulled.

This is especially useful for:

• Supporting both x86 and ARM-based devices
• Ensuring your applications run on various cloud providers
• Building for IoT devices with different architectures

Setting Up for Multi-Architecture Builds

Docker Buildx needs to be configured for multi-architecture builds. First, let's ensure our builder supports this feature:

docker buildx inspect --bootstrap mybuilder

If you see an error about the builder not being available, let's recreate it with the right configuration:

docker buildx rm mybuilder
docker buildx create --name mybuilder --driver docker-container --bootstrap --use

Creating a Multi-Architecture Image

Now let's build our Nginx image for multiple architectures:

docker buildx build --platform linux/amd64,linux/arm64 -t nginx-test:multi .

You might see an error message similar to:

error: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")

This happens because the default Docker driver doesn't support multi-architecture builds. Let's modify our approach.

For demonstration purposes, we'll build for specific platforms separately:

docker buildx build --platform linux/amd64 -t nginx-test:amd64 --load .

This builds the image specifically for the AMD64 architecture and loads it into Docker's local image store.

Using Build Arguments

Docker Buildx allows us to use build arguments to customize our builds. Let's modify our Dockerfile to use a build argument:

nano Dockerfile

Update the Dockerfile content to:

FROM ubuntu:22.04

ARG PACKAGE=nginx
RUN apt-get update && apt-get install -y \
  curl \
  ${PACKAGE} \
  && rm -rf /var/lib/apt/lists/*

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Press Ctrl+O followed by Enter to save, then Ctrl+X to exit nano.

Now we can build the image with a custom package:

docker buildx build --build-arg PACKAGE=nginx-extras -t nginx-extras:latest .

Pushing to a Registry (Optional)

To fully utilize multi-architecture images, you'd typically push them to a registry. This requires Docker Hub credentials or a private registry. In a real-world scenario, the command would look like:

## Example only - not required for this lab
## docker buildx build --platform linux/amd64,linux/arm64 -t username/nginx-test:multi --push .

Inspecting Images

Let's examine the images we've created:

docker images | grep nginx

You should see output similar to:

nginx-extras    latest     abcdef123456   1 minute ago    130MB
nginx-test      amd64      123456abcdef   2 minutes ago   123MB
nginx-test      latest     fedcba654321   10 minutes ago  123MB

Testing Our Image

Finally, let's run a container using our image to verify it works:

docker run -d --name test-nginx -p 8080:80 nginx-test:latest

Check if the container is running:

docker ps

You should see output indicating your container is running:

CONTAINER ID   IMAGE              COMMAND                  CREATED          STATUS          PORTS                  NAMES
abcdef123456   nginx-test:latest  "nginx -g 'daemon of…"   10 seconds ago   Up 10 seconds   0.0.0.0:8080->80/tcp   test-nginx

Let's curl the nginx server to make sure it's responding:

curl http://localhost:8080

You should see the default Nginx welcome page HTML.

When you're done, clean up the container:

docker stop test-nginx
docker rm test-nginx

Congratulations! You've successfully worked with Docker Buildx, understood and resolved the "requires exactly 1 argument" error, and learned how to create specialized builds for different architectures.

Summary

In this lab, you gained practical experience with Docker Buildx and learned how to troubleshoot the common "requires exactly 1 argument" error. Here's what you accomplished:

1. Set up Docker Buildx and created a builder instance
2. Created a basic Dockerfile for testing
3. Encountered, understood, and resolved the "requires exactly 1 argument" error
4. Built Docker images with various options and configurations
5. Learned the basics of multi-architecture image building

These skills provide a solid foundation for working with Docker in modern development environments, where applications often need to run on diverse hardware platforms. You can now confidently use Docker Buildx to create efficient, platform-specific container images while avoiding common errors.

As you continue your Docker journey, consider exploring more advanced Buildx features, integrating it into CI/CD pipelines, and using it to build truly portable applications that can run anywhere.