5.3 KiB
5.3 KiB
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
cd spore-deployment
./scripts/setup-multiarch.sh
Option 2: Manual Setup
# 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:
# 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:
# 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
- Docker Buildx - Uses Docker's extended build capabilities
- QEMU Emulation - Allows building ARM images on x86_64 machines
- Multi-platform build - Creates a single image manifest supporting multiple architectures
- Automatic selection - Docker automatically pulls the correct architecture for the host system
Verifying Multiarch Images
Check which architectures are supported:
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:
docker pull wirelos/spore-gateway:latest
# Docker automatically uses amd64 version
On Raspberry Pi (ARM64):
docker pull wirelos/spore-gateway:latest
# Docker automatically uses arm64 version
Docker Compose
The existing docker-compose.yml works automatically with multiarch images:
cd spore-deployment
make up
Docker Compose will pull the correct architecture for your system.
Nomad Deployment
Multiarch images work automatically with Nomad:
cd spore-deployment
make nomad-job-run
Nomad will schedule pods based on available nodes and their architectures.
Troubleshooting
Check Available Platforms
docker buildx inspect multiarch
Switch Builders
# Use multiarch builder
docker buildx use multiarch
# Use default builder
docker buildx use default
Remove and Recreate Builder
docker buildx rm multiarch
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap
Build for Specific Platform Only
# 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
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