spore-deployment/docs/DOCKER.md

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:

# 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:

# 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:

# 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:

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:

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:

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:

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:

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:

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:

# 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