How to Deploy & Use docker/buildx

# Docker Buildx Deployment and Usage Guide

Complete guide for installing, configuring, and deploying Docker Buildx, the Docker CLI plugin for extended build capabilities with BuildKit.

## 1. Prerequisites

### Required Runtime
- **Docker Engine**: Version 19.03 or newer (required for CLI plugin support)
- **BuildKit**: Included with Docker Engine 19.03+ (Buildx uses BuildKit internally)

### For Building from Source
- **Go**: Version 1.20 or newer
- **Git**: For cloning repositories
- **Make**: For using Makefile targets
- **Docker**: With BuildKit enabled (for containerized builds)

### For Multi-Platform Builds
- **QEMU**: For emulation support (`docker run --privileged --rm tonistiigi/binfmt --install all`)
- **Kubernetes cluster**: Optional, for using the Kubernetes driver

## 2. Installation

### Method A: Docker Desktop (Windows/macOS)
Buildx is included automatically with [Docker Desktop](https://docs.docker.com/desktop/). No additional installation required.

Verify installation:
```bash
docker buildx version

Method B: Linux Package Managers

Install via official Docker repositories:

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install docker-buildx-plugin

RHEL/CentOS/Fedora:

sudo dnf install docker-buildx-plugin

Verify:

docker buildx version

Method C: Manual Binary Installation

Download from GitHub Releases:

Linux/macOS:

# Download latest release (adjust version as needed)
curl -L https://github.com/docker/buildx/releases/download/v0.12.0/buildx-v0.12.0.linux-amd64 -o docker-buildx

# Create plugin directory
mkdir -p ~/.docker/cli-plugins

# Move binary and make executable
mv docker-buildx ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx

Windows:

# Download buildx-v0.12.0.windows-amd64.exe
# Move to:
# %USERPROFILE%\.docker\cli-plugins\docker-buildx.exe

System-wide Installation (Unix):

# Copy to system plugin directory
sudo cp ~/.docker/cli-plugins/docker-buildx /usr/local/lib/docker/cli-plugins/
# or
sudo cp ~/.docker/cli-plugins/docker-buildx /usr/lib/docker/cli-plugins/

Method D: Build from Source

Option 1: Using Bake (Recommended for Buildx 0.6+):

docker buildx bake "https://github.com/docker/buildx.git"
mkdir -p ~/.docker/cli-plugins
mv ./bin/build/buildx ~/.docker/cli-plugins/docker-buildx

Option 2: Using Docker Build (Docker 19.03+):

DOCKER_BUILDKIT=1 docker build --platform=local -o . "https://github.com/docker/buildx.git"
mkdir -p ~/.docker/cli-plugins
mv buildx ~/.docker/cli-plugins/docker-buildx

Option 3: Local Clone:

git clone https://github.com/docker/buildx.git && cd buildx
make install

Method E: Dockerfile Installation

Use in multi-stage builds or CI pipelines:

# syntax=docker/dockerfile:1
FROM docker
COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-buildx
RUN docker buildx version

3. Configuration

Environment Variables

Builder Instance Configuration

Create a new builder with specific drivers:

Docker Container Driver (default):

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

Kubernetes Driver:

docker buildx create --name kubebuilder --driver kubernetes --use

Remote Driver:

docker buildx create --name remote --driver remote tcp://buildkit-server:1234

Multi-Platform Configuration

Enable QEMU emulation for cross-platform builds:

docker run --privileged --rm tonistiigi/binfmt --install all

Verify platforms:

docker buildx inspect --bootstrap

Config Files

Builder state stored in:

• Linux/macOS: ~/.docker/buildx/
• Windows: %USERPROFILE%\.docker\buildx\

4. Build & Run

Verify Installation

docker buildx version
docker buildx ls

Basic Usage

Build with default builder:

docker buildx build .

Build with specific builder:

docker buildx build --builder mybuilder .

Build and load into local Docker:

docker buildx build --load -t myimage:latest .

Build and push to registry:

docker buildx build --push -t username/repo:tag .

Multi-platform build:

docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 --push -t username/repo:tag .

Development Workflow

Build the plugin locally:

cd buildx
make build

Install to local plugins:

make install
# Equivalent to:
# go build -o ~/.docker/cli-plugins/docker-buildx ./cmd/buildx

Run tests:

make test

Lint code:

make lint

5. Deployment

CI/CD Pipeline Deployment

GitHub Actions:

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3
  with:
    version: latest
    driver: docker-container

GitLab CI:

build:
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - mkdir -p ~/.docker/cli-plugins
    - curl -L https://github.com/docker/buildx/releases/latest/download/buildx-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-buildx
    - chmod +x ~/.docker/cli-plugins/docker-buildx
  script:
    - docker buildx build --push -t $CI_REGISTRY_IMAGE .

Jenkins (Kubernetes): Deploy Buildx with Kubernetes driver for distributed builds:

docker buildx create --name jenkins-builder --driver kubernetes --driver-opt replicas=3,namespace=jenkins --use

Container Deployment

Use docker/buildx-bin image for sidecar containers:

# Kubernetes sidecar example
- name: buildx
  image: docker/buildx-bin:latest
  volumeMounts:
    - name: docker-plugins
      mountPath: /usr/libexec/docker/cli-plugins

Production Builder Setup

High-Availability Builder:

# Create multi-node builder
docker buildx create --name prod-builder --node node1 --driver docker-container tcp://host1:2376
docker buildx create --name prod-builder --node node2 --driver docker-container tcp://host2:2376 --append
docker buildx use prod-builder
docker buildx inspect --bootstrap

Remote BuildKit Cluster:

docker buildx create \
  --name remote-builder \
  --driver remote \
  --driver-opt cert=/certs/client-cert.pem,key=/certs/client-key.pem,ca=/certs/ca.pem \
  tcp://buildkit-cluster:1234

6. Troubleshooting

Plugin Not Found

Symptom: docker: 'buildx' is not a docker command

Solutions:

# Check plugin location
ls -la ~/.docker/cli-plugins/docker-buildx

# Verify executable permissions
chmod +x ~/.docker/cli-plugins/docker-buildx

# Check Docker version (must be 19.03+)
docker version

# Verify plugin path
docker info --format '{{.ClientInfo.Plugins}}'

BuildKit Daemon Issues

Symptom: error: failed to solve: rpc error: code = Unknown

Solutions:

# Inspect builder
docker buildx inspect --bootstrap

# Remove and recreate builder
docker buildx rm mybuilder
docker buildx create --name mybuilder --use

# Check BuildKit logs (for container driver)
docker logs buildx_buildkit_mybuilder0

Multi-Platform Build Failures

Symptom: error: multiple platforms feature is currently not supported for docker driver

Solution:

# Must use docker-container or kubernetes driver for multi-platform
docker buildx create --name multiplatform --driver docker-container --use
docker buildx inspect --bootstrap

Permission Denied (Linux)

Symptom: permission denied while trying to connect to the Docker daemon

Solution:

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker

Version Compatibility

Symptom: Unexpected behavior with newer BuildKit features

Check versions:

docker version
docker buildx version
docker buildx inspect --bootstrap | grep BuildKit

Update Buildx:

# Download latest release and replace binary
curl -L https://github.com/docker/buildx/releases/latest/download/buildx-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx

Kubernetes Driver Connection Issues

Symptom: error: failed to dial BuildKit: connection refused

Solutions:

# Verify BuildKit pods are running
kubectl get pods -n default -l app=buildkit

# Check service endpoints
kubectl get svc -l app=buildkit

# Recreate builder with explicit namespace
docker buildx create --name k8s-builder --driver kubernetes --driver-opt namespace=default,image=moby/buildkit:master --use