# ARM & Multi-Architecture Docker

## The Problem
- Docker images are built for a specific CPU architecture (amd64, arm64, armv7, etc.)
- Running an amd64 image on ARM64 (Raspberry Pi, Apple Silicon) fails with:
  - `no matching manifest for linux/arm64`
  - `exec format error`
- Even if an image starts via QEMU emulation, it will be 5–10× slower

## Checking Image Architecture Support
- Docker Hub: look for "OS/ARCH" tags on the image page
- CLI: `docker manifest inspect <image>` — look for `platform.architecture`
- Quick test: `docker run --rm <image> uname -m` — shows the architecture inside the container

## ARM-Compatible Image Strategies

### 1. Use Official Multi-Arch Images (Best)
Most official images support multiple architectures automatically:
- `node:18-alpine` — amd64, arm64, armv7
- `postgres:16-alpine` — amd64, arm64
- `redis:7-alpine` — amd64, arm64
- `python:3.12-slim` — amd64, arm64

Docker automatically pulls the right variant for your host.

### 2. Use Alpine-Based Images
Alpine Linux has excellent ARM support. Prefer `-alpine` variants:
- Smaller image size (5MB base vs 80MB for Debian)
- Native ARM64 support
- Trade-off: uses `musl` instead of `glibc` — rare compatibility issues with some native modules

### 3. Build from Source
When no ARM image exists, build locally:
```yaml
services:
  app:
    build: .
    # No 'image:' tag — Docker builds for the host architecture automatically
```

### 4. Cross-Architecture Builds with Buildx
Build images for multiple architectures:
```bash
# One-time setup
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

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

## QEMU Emulation (Last Resort)
- Docker Desktop includes QEMU for transparent emulation
- On Linux: `docker run --rm --privileged multiarch/qemu-user-static --reset -p yes`
- Performance: 5–10× slower than native. Acceptable for CI, not for production

## Raspberry Pi Specifics
- **Architecture**: armv7 (32-bit) for Pi 3 and older, arm64 for Pi 4+ with 64-bit OS
- **Memory**: Pi 4 has 1–8GB RAM. Set container memory limits to avoid OOM:
  ```yaml
  deploy:
    resources:
      limits:
        memory: 512M
  ```
- **SD Card I/O**: Very slow. Move Docker data directory to USB/SSD for better performance
- **Swap**: Enable at least 1GB swap for build operations: `sudo dphys-swapfile setup`
- **Temperature**: Intensive builds may throttle. Monitor with `vcgencmd measure_temp`

## Apple Silicon (M1/M2/M3/M4) Specifics
- **Architecture**: arm64 (aarch64)
- Docker Desktop runs a Linux VM with native arm64 support
- Rosetta 2 integration: Docker Desktop can use Rosetta for amd64 images (faster than QEMU)
  - Enable in Docker Desktop → Settings → General → "Use Rosetta for x86_64/amd64 emulation"
- Most popular images already have arm64 variants — rarely need emulation

## Common Errors & Fixes
| Error | Cause | Fix |
|-------|-------|-----|
| `no matching manifest for linux/arm64` | Image doesn't support ARM | Find an alternative image or build from source |
| `exec format error` | Binary compiled for wrong arch | Use multi-arch image or rebuild |
| `segmentation fault` | QEMU emulation bug | Build natively on ARM instead of emulating |
| Build hangs / extremely slow | QEMU emulation overhead | Build on native ARM hardware or use buildx |
