Docker Multi-Platform Build Failing for ARM64/AMD64: How to Fix It

# Check current builder
docker buildx ls
# If only "default" exists, create a new builder
 
# Create a multi-platform builder
docker buildx create --name multiplatform --driver docker-container --use
 
# Verify it's active
docker buildx ls
# Should show "multiplatform" with *
 
# Bootstrap the builder
docker buildx inspect --bootstrap

# Install QEMU on Linux
docker run --privileged --rm tonistiigi/binfmt --install all
 
# Verify QEMU is installed
ls /proc/sys/fs/binfmt_misc/ | grep qemu
# Should show: qemu-aarch64, qemu-arm, etc.
 
# Verify in BuildKit
docker buildx inspect multiplatform
# Should show: Platforms: linux/amd64, linux/arm64, linux/arm/v7, ...

# Build and push to registry (most common)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag myrepo/myapp:latest \
  --push \
  .
 
# Build to local Docker daemon (only one platform at a time locally)
docker buildx build \
  --platform linux/arm64 \
  --tag myapp:arm64 \
  --load \  # --load only works with single platform
  .
 
# Build and save as tar (both platforms)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag myapp:latest \
  --output type=oci,dest=./myapp.tar \
  .

FROM ubuntu:22.04
 
# Use TARGETPLATFORM to handle differences
ARG TARGETPLATFORM
ARG TARGETOS
ARG TARGETARCH
 
# Download platform-specific binary
RUN case ${TARGETPLATFORM} in \
  "linux/amd64") ARCH=amd64 ;; \
  "linux/arm64") ARCH=arm64 ;; \
  "linux/arm/v7") ARCH=armv7 ;; \
  *) echo "Unsupported platform: ${TARGETPLATFORM}" && exit 1 ;; \
esac && \
wget https://example.com/binary-${ARCH} -O /usr/local/bin/mybinary && \
chmod +x /usr/local/bin/mybinary

FROM golang:1.22 AS builder
 
ARG TARGETOS
ARG TARGETARCH
 
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o server ./cmd/server

name: Build Multi-Platform
 
on:
  push:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            myrepo/myapp:latest
            myrepo/myapp:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

jobs:
  build-amd64:
    runs-on: ubuntu-latest  # AMD64
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - name: Build AMD64
        uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64
          push: true
          tags: myrepo/myapp:amd64
  
  build-arm64:
    runs-on: ubuntu-24.04-arm  # GitHub's native ARM64 runner
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - name: Build ARM64
        uses: docker/build-push-action@v5
        with:
          platforms: linux/arm64
          push: true
          tags: myrepo/myapp:arm64
  
  merge-manifest:
    needs: [build-amd64, build-arm64]
    runs-on: ubuntu-latest
    steps:
      - name: Create manifest
        run: |
          docker buildx imagetools create \
            --tag myrepo/myapp:latest \
            myrepo/myapp:amd64 \
            myrepo/myapp:arm64

# Check what platforms the image supports
docker buildx imagetools inspect myrepo/myapp:latest
 
# Output should show:
# Manifests:
#   linux/amd64:
#     MediaType: application/vnd.oci.image.manifest.v1+json
#     ...
#   linux/arm64:
#     MediaType: application/vnd.oci.image.manifest.v1+json
#     ...
 
# Pull and run on specific platform
docker run --platform linux/arm64 myrepo/myapp:latest uname -m
# aarch64
 
docker run --platform linux/amd64 myrepo/myapp:latest uname -m
# x86_64