Multi-Architecture Builds

Guide for building and deploying Cbox images across AMD64 (x86_64) and ARM64 (aarch64) platforms.

Platform Support

Cbox Base Images are built for both architectures:

Quick Start

Pull Multi-Arch Images

Docker automatically selects the correct architecture:

# Works on both AMD64 and ARM64
docker pull ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

Build Multi-Platform Images

Use Docker Buildx for multi-architecture builds:

# Create builder instance (one-time setup)
docker buildx create --name multiarch --driver docker-container --use

# Build for both platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push .

ARM64 Optimization

Apple Silicon (M1/M2/M3) Development

Cbox images run natively on Apple Silicon without emulation:

# docker-compose.yml for Apple Silicon
version: '3.8'

services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    platform: linux/arm64  # Native ARM64
    ports:
      - "8000:80"
    volumes:
      - ./:/var/www/html

Performance tip: Native ARM64 images are 2-3x faster than emulated AMD64 on Apple Silicon.

AWS Graviton Deployment

For cost-effective AWS deployments on Graviton instances:

# ECS Task Definition
{
  "family": "cbox-app",
  "runtimePlatform": {
    "cpuArchitecture": "ARM64",
    "operatingSystemFamily": "LINUX"
  },
  "containerDefinitions": [
    {
      "name": "app",
      "image": "ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm",
      "portMappings": [
        { "containerPort": 80, "protocol": "tcp" }
      ]
    }
  ]
}

Cost savings: Graviton instances typically offer 20-40% better price/performance.

Building Custom Multi-Arch Images

Using Dockerfile.production Template

The production template supports multi-architecture builds out of the box:

# Build and push multi-platform image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target production \
  -t ghcr.io/yourorg/myapp:latest \
  -f templates/Dockerfile.production \
  --push .

CI/CD Multi-Platform Builds

GitHub Actions

name: Build Multi-Platform

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: linux-latest  # Use your CI provider's Linux runner
    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 GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

GitLab CI

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_BUILDKIT: 1
  before_script:
    - docker buildx create --use
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker buildx build
        --platform linux/amd64,linux/arm64
        --push
        -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
        -t $CI_REGISTRY_IMAGE:latest .

Architecture-Specific Considerations

Extension Compatibility

All Cbox extensions are available on both architectures:

Performance Differences

Image Sizes

Troubleshooting

Emulation Performance Issues

If you see slow performance on Apple Silicon:

# Check if running under emulation
docker run --rm ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm uname -m
# Should output: aarch64 (not x86_64)

Fix: Ensure you're pulling ARM64 images:

# Force ARM64 architecture
docker pull --platform linux/arm64 ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

Build Failures on ARM64

Some PECL extensions may need source compilation on ARM64:

# Example: Building custom extension for ARM64
FROM ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

# Ensure build tools are available
RUN apt-get update && apt-get install -y $PHPIZE_DEPS

# Install extension from source
RUN pecl install some-extension && \
    docker-php-ext-enable some-extension && \
    apk del $PHPIZE_DEPS

Cross-Platform Testing

Test your image on both architectures locally:

# Test AMD64 build (on ARM64 machine)
docker run --platform linux/amd64 --rm myapp:latest php -v

# Test ARM64 build (on AMD64 machine)
docker run --platform linux/arm64 --rm myapp:latest php -v

Best Practices

1. Use Multi-Platform Manifests

Always build and push multi-platform images:

# Build manifest with both architectures
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:v1.0.0 \
  --push .

2. Pin Architecture When Needed

For reproducibility in production:

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
    platform: linux/amd64  # Pin to specific architecture

3. Cache Multi-Platform Builds

Use registry caching for faster CI builds:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-from type=registry,ref=myapp:cache \
  --cache-to type=registry,ref=myapp:cache,mode=max \
  -t myapp:latest \
  --push .

4. Test on Target Architecture

Always test on the deployment architecture:

# GitHub Actions: Test on ARM64 runner
jobs:
  test-arm64:
    runs-on: linux-arm64  # Use your CI provider's ARM64 runner
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: docker run --rm myapp:latest php artisan test

Kubernetes Multi-Architecture

Mixed Architecture Clusters

For clusters with both AMD64 and ARM64 nodes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cbox-app
spec:
  template:
    spec:
      # Allow scheduling on any architecture
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: kubernetes.io/arch
                    operator: In
                    values:
                      - amd64
                      - arm64
      containers:
        - name: app
          image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm

Architecture-Specific Scheduling

For workloads that perform better on specific architectures:

# Schedule on ARM64 nodes for cost optimization
spec:
  nodeSelector:
    kubernetes.io/arch: arm64

References

• Docker Buildx Documentation
• AWS Graviton Getting Started
• Apple Silicon Docker Guide
• Kubernetes Multi-Architecture

Need help? GitHub Discussions | Performance Tuning