# 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