feat: multiarch build

docs/MULTIARCH.md

@@ -0,0 +1,235 @@
+# 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/)
+