Multi-architecture builds with buildx

Key points

• An image is built for one architecture. Pull an amd64 image onto arm64 and it either refuses or crawls under emulation.
• docker buildx build --platform linux/amd64,linux/arm64 builds both and publishes a manifest list under one tag.
• The client picks the matching image automatically, so the same myapp:1.0 reference works on every machine.
• Cross-building Java is cheap: the jar is architecture-neutral, so only the base image and any native library differ.
• Multi-arch needs --push. A manifest list cannot live in the local image store, only in a registry.
• Emulated builds are slow. Run the Maven stage once on the native arch and copy the jar into both runtime stages.

Example

# one builder that can target several platforms
docker buildx create --name multi --driver docker-container --use
docker buildx inspect --bootstrap

# build both and publish a single tag pointing at both
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/acme/myapp:1.0 \
  --push .

# what is behind that tag now?
docker buildx imagetools inspect ghcr.io/acme/myapp:1.0
#   linux/amd64  sha256:...
#   linux/arm64  sha256:...

# force one architecture locally (slow, but it runs)
docker run --rm --platform linux/amd64 ghcr.io/acme/myapp:1.0 java -version

One tag, a manifest list behind it, and nobody has to know which chip they are on.