spore-deployment/docs/MULTIARCH.md

# Multiarch Docker Images for SPORE

This guide explains how to build and deploy SPORE Docker images that support multiple architectures (amd64 and arm64).

## Overview

SPORE services can run on both x86_64 (amd64) and ARM64 systems (including Raspberry Pi). To support both architectures, we use Docker's buildx feature to create multiarch images.

## Supported Architectures

- **linux/amd64** - Intel/AMD 64-bit processors
- **linux/arm64** - ARM 64-bit processors (Raspberry Pi 4+, Apple Silicon, etc.)

## Setup (One-Time)

### Option 1: Automated Setup Script

```bash
cd spore-deployment
./scripts/setup-multiarch.sh
```

### Option 2: Manual Setup

```bash
# Install QEMU emulation for cross-architecture builds
docker run --rm --privileged tonistiigi/binfmt:latest --install all

# Create and configure the multiarch builder
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

# Verify setup
docker buildx ls
```

You should see a builder named `multiarch` with support for `linux/amd64` and `linux/arm64`.

## Building Multiarch Images

### All Services at Once

From the `spore-deployment` directory:

```bash
# Build and push all multiarch images
make push-multiarch

# Build without pushing (for local testing)
make build-multiarch

# Build with custom tag
make push-multiarch IMAGE_TAG=v1.0.0
```

### Individual Services

From each service directory:

```bash
# spore-gateway
cd spore-gateway
make docker-build-multiarch

# spore-registry
cd spore-registry
make docker-build-multiarch

# spore-ledlab
cd spore-ledlab
make docker-build-multiarch

# spore-ui
cd spore-ui
make docker-build-multiarch
```

## How It Works

1. **Docker Buildx** - Uses Docker's extended build capabilities
2. **QEMU Emulation** - Allows building ARM images on x86_64 machines
3. **Multi-platform build** - Creates a single image manifest supporting multiple architectures
4. **Automatic selection** - Docker automatically pulls the correct architecture for the host system

## Verifying Multiarch Images

Check which architectures are supported:

```bash
docker buildx imagetools inspect wirelos/spore-gateway:latest
```

Output should show both:
- linux/amd64
- linux/arm64

## Using Multiarch Images

Once pushed to a registry, images are automatically used by Docker based on the host architecture:

**On x86_64 systems:**
```bash
docker pull wirelos/spore-gateway:latest
# Docker automatically uses amd64 version
```

**On Raspberry Pi (ARM64):**
```bash
docker pull wirelos/spore-gateway:latest
# Docker automatically uses arm64 version
```

## Docker Compose

The existing `docker-compose.yml` works automatically with multiarch images:

```bash
cd spore-deployment
make up
```

Docker Compose will pull the correct architecture for your system.

## Nomad Deployment

Multiarch images work automatically with Nomad:

```bash
cd spore-deployment
make nomad-job-run
```

Nomad will schedule pods based on available nodes and their architectures.

## Troubleshooting

### Check Available Platforms

```bash
docker buildx inspect multiarch
```

### Switch Builders

```bash
# Use multiarch builder
docker buildx use multiarch

# Use default builder
docker buildx use default
```

### Remove and Recreate Builder

```bash
docker buildx rm multiarch
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap
```

### Build for Specific Platform Only

```bash
# Build only for ARM64
docker buildx build --platform linux/arm64 -t wirelos/spore-gateway:latest .

# Build only for AMD64
docker buildx build --platform linux/amd64 -t wirelos/spore-gateway:latest .
```

### Common Issues

#### Error: "multiple platforms feature is currently not supported"
- Solution: Enable buildkit: `export DOCKER_CLI_EXPERIMENTAL=enabled`

#### Error: "failed to solve: failed to compute cache key"
- Solution: Make sure all source files are present in build context

#### Slow builds on first run
- Normal: QEMU emulation is slower than native builds
- Subsequent builds use Docker layer cache and are faster

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Build and Push Multiarch

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      
      - name: Build and push
        run: |
          cd spore-deployment
          make push-multiarch IMAGE_TAG=${{ github.sha }}
```

## Security Considerations

- Multiarch images are signed for each platform
- When using third-party base images, ensure they also support multiarch
- Test on both architectures before production deployment

## Performance Notes

### Build Performance

- Native builds (build on the target architecture): Fastest
- Cross-compilation (build on different architecture): Slower but convenient
- Emulation via QEMU: Slowest but allows building all architectures on one machine

### Runtime Performance

- No difference: Once the correct architecture image is pulled, performance is the same as single-arch builds

## Additional Resources

- [Docker Buildx Documentation](https://docs.docker.com/buildx/)
- [Docker Multiarch Tutorial](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/)
- [QEMU Documentation](https://www.qemu.org/documentation/)