Building an AMD64 Docker Image on ARM-based Mac

BUILDING_AMD64_DOCKER_IMAGE.md

Building an AMD64 Docker Image on ARM-based Mac

This guide documents the successful process for building an AMD64-compatible Docker image on an ARM-based Mac.

Prerequisites

• Docker Desktop with buildx support installed
• ARM-based Mac (M1, M2, etc.)
• A Docker buildx builder for AMD64 architecture

Step 1: Check Available Builders

First, check available buildx builders to see if an AMD64 builder already exists:

docker buildx ls

Look for a builder with AMD64 platform support. In our case, we saw:

NAME/NODE                DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
amd64-builder*           docker-container                         
 \_ amd64-builder0        \_ desktop-linux   running   v0.20.2    linux/amd64 (+2), linux/arm64, linux/arm (+2), ...

Step 2: Choose the Right Build Approach

DO:

• Use a pre-existing AMD64 image as a base for your custom image
• Add your customizations on top
• Use the proper platform flags and Docker buildx

DON'T:

• Try to build from scratch with complex dependencies that might not cross-compile correctly
• Use standard docker build without platform specification
• Attempt to run intensive build operations (like Prisma client generation) during cross-compilation as they often fail

Step 3: Create a Custom Dockerfile

Create a Dockerfile (e.g., Dockerfile.amd64-custom) that uses an official base image:

FROM --platform=linux/amd64 ghcr.io/linkwarden/linkwarden:latest

# Copy your customizations
COPY . /data/

# Set your environment variables
ENV MAX_WORKERS=2 \
    SEQUENTIAL_PROCESSING=true \
    IMAGE_QUALITY=70 \
    LOW_RESOURCE_MODE=true

# The container will use the built-in command
CMD ["yarn", "start"]

Step 4: Build the AMD64 Image

Use Docker buildx to build the image for AMD64 architecture:

docker buildx build --platform linux/amd64 -t yourapp:amd64-custom -f Dockerfile.amd64-custom --load .

Key parameters:

• --platform linux/amd64: Specifies the target platform
• --load: Makes the image available in your local Docker images
• -f Dockerfile.amd64-custom: Uses your custom Dockerfile

Step 5: Verify the Image

Check that the image was created with the correct architecture:

docker images | grep yourapp

Step 6: Save the Image for Transfer

Save the image to a tar file for transfer to your AMD64 server:

docker save yourapp:amd64-custom -o yourapp-amd64-custom.tar

Step 7: Transfer and Load on Target Server

1. Transfer the tar file to your AMD64 server
2. Load the image on the server:

docker load -i yourapp-amd64-custom.tar

Common Issues and Solutions

1. Compilation Errors: If you encounter errors during complex build steps (like compiling native dependencies), use a pre-built base image and add your customizations on top instead of building from scratch.

2. Platform Specification: Always explicitly specify --platform linux/amd64 in your Docker build commands.

3. Performance: Cross-architecture builds are slower than native builds. Be patient during the build process.

4. Docker buildx Cache: If you face cache issues, use --no-cache flag to start fresh.

Example of Failed Approach

DO NOT attempt to build complex applications from scratch with dependencies that need compilation:

# This approach often fails with cross-compilation errors
docker buildx build --platform linux/amd64 -t yourapp:amd64 -f Dockerfile .

The error typically looks like:

ERROR: process "/bin/sh -c yarn prisma generate && yarn build" did not complete successfully: exit code: 133

Instead, use pre-built images as a base and add your customizations on top, as shown in the successful approach.