feat: multiarch build

docs/DOCKER.md

@@ -0,0 +1,180 @@
+# SPORE Docker Build Guide
+
+This document provides instructions for building and running SPORE services as Docker containers.
+
+## Prerequisites
+
+- Docker installed on your system
+- Docker Compose (optional, for running multiple services)
+
+## Building Docker Images
+
+### Using Makefiles
+
+Each project includes a Makefile with Docker targets for easy building and pushing:
+
+```bash
+# Build Docker image (single architecture)
+make docker-build
+
+# Push Docker image (optional, requires DOCKER_REGISTRY variable)
+make docker-push
+```
+
+**Optional**: Specify a Docker registry and tag:
+
+```bash
+# Build with custom tag
+make docker-build IMAGE_TAG=v1.0.0
+
+# Push to custom registry
+make docker-push DOCKER_REGISTRY=your-registry.com IMAGE_TAG=v1.0.0
+```
+
+### Building Multiarch Images (amd64 & arm64)
+
+For Raspberry Pi and other ARM devices, build multiarch images:
+
+```bash
+# One-time setup for buildx
+docker run --rm --privileged tonistiigi/binfmt:latest --install all
+docker buildx create --name multiarch --use
+docker buildx inspect --bootstrap
+
+# Build and push multiarch images
+make docker-build-multiarch IMAGE_TAG=latest
+```
+
+This builds images for both `linux/amd64` and `linux/arm64` architectures simultaneously.
+
+### Direct Docker Commands
+
+### spore-gateway
+
+From the `spore-gateway` directory:
+
+```bash
+docker build -t spore-gateway:latest .
+docker run -p 3001:3001 -p 4210:4210/udp spore-gateway:latest
+```
+
+### spore-ledlab
+
+From the `spore-ledlab` directory:
+
+```bash
+docker build -t spore-ledlab:latest .
+docker run -p 8080:8080 --env GATEWAY_URL=http://localhost:3001 spore-ledlab:latest
+```
+
+### spore-registry
+
+From the `spore-registry` directory:
+
+```bash
+docker build -t spore-registry:latest .
+docker run -p 8080:8080 -v registry-data:/data/registry spore-registry:latest
+```
+
+Note: The registry data is stored in a Docker volume for persistence.
+
+### spore-ui
+
+From the `spore-ui` directory:
+
+```bash
+docker build -t spore-ui:latest .
+docker run -p 3000:3000 spore-ui:latest
+```
+
+## Environment Variables
+
+### spore-ledlab
+
+- `PORT`: Server port (default: 8080)
+- `UDP_PORT`: UDP discovery port (default: 4210)
+- `GATEWAY_URL`: Gateway URL (default: http://localhost:3001)
+- `FILTER_APP_LABEL`: Filter app label (default: pixelstream)
+- `MATRIX_WIDTH`: Matrix width (default: 16)
+- `MATRIX_HEIGHT`: Matrix height (default: 16)
+
+### spore-gateway
+
+- HTTP server port: 3001 (override with `-port` flag)
+- UDP discovery port: 4210 (override with `-udp-port` flag)
+- Log level (default: info, override with `-log-level` flag)
+
+### spore-ui
+
+- `PORT`: Server port (default: 3000)
+
+## Docker Compose (Optional)
+
+You can create a `docker-compose.yml` file to run all services together:
+
+```yaml
+version: '3.8'
+
+services:
+  gateway:
+    build: ./spore-gateway
+    ports:
+      - "3001:3001"
+      - "4210:4210/udp"
+    
+  ledlab:
+    build: ./spore-ledlab
+    ports:
+      - "8080:8080"
+    environment:
+      - GATEWAY_URL=http://gateway:3001
+    depends_on:
+      - gateway
+    
+  registry:
+    build: ./spore-registry
+    ports:
+      - "8090:8080"
+    volumes:
+      - registry-data:/data/registry
+    
+  ui:
+    build: ./spore-ui
+    ports:
+      - "3000:3000"
+
+volumes:
+  registry-data:
+```
+
+Then run:
+
+```bash
+docker-compose up -d
+```
+
+## Troubleshooting
+
+### Port Conflicts
+
+If ports are already in use, modify the port mappings in the `docker run` commands or in the `docker-compose.yml` file.
+
+### Registry Data Persistence
+
+The spore-registry service uses a Docker volume to persist data. To backup or restore:
+
+```bash
+# Backup
+docker run --rm -v registry-data:/data -v $(pwd):/backup alpine tar czf /backup/registry-backup.tar.gz /data
+
+# Restore
+docker run --rm -v registry-data:/data -v $(pwd):/backup alpine tar xzf /backup/registry-backup.tar.gz -C /
+```
+
+### Network Configuration
+
+When running services in separate containers, make sure they can reach each other. Either:
+- Use Docker networking with docker-compose
+- Use host networking: `--network host`
+- Update service URLs to point to appropriate hosts/containers
+