SPORE Deployment

Complete deployment configurations for running the SPORE stack with Docker Compose or HashiCorp Nomad.

Overview

This repository provides two deployment options:

1. Docker Compose - Simple deployment with docker-compose for development and production
2. Nomad - Production-ready orchestration using HashiCorp Nomad

Both deployments include all SPORE services with proper networking, volumes, and service discovery.

Services

• mosquitto: MQTT broker for message routing (port 1883, 9001)
• spore-gateway: Node discovery and WebSocket gateway with MQTT integration (port 3001, UDP 4210)
• spore-registry: Firmware registry service (port 8090)
• spore-ledlab: LED animation studio (port 8080)
• spore-ui: Web UI for cluster management (port 3000)

Prerequisites

For Docker Compose

• Docker and Docker Compose installed
• Available ports: 1883, 3000, 3001, 4210, 8080, 8090

For Nomad

• HashiCorp Nomad installed
• Docker installed (Nomad uses Docker to run containers)
• Available ports: 1883, 3000, 3001, 4210, 8080, 8090, 4646

Deployment Options

Option 1: Docker Compose (Recommended for development)

Simple, single-node deployment with docker-compose.

Quick Start

cd spore-deployment

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

Services Access

• Web UI: http://localhost:3000
• LED Lab: http://localhost:8080
• Registry API: http://localhost:8090
• Gateway API: http://localhost:3001
• MQTT Broker: tcp://localhost:1883 (WebSocket: ws://localhost:9001)

Data Storage

All data is persisted in local ./data/ directory:

• Registry data: ./data/registry
• MQTT data: ./data/mqtt/

Management

# View logs for all services
make logs

# View logs for specific service
make gateway-logs
make registry-logs
make ledlab-logs
make ui-logs
make mqtt-logs

# Restart services
make restart

# Clean (stop and remove all data)
make clean

Option 2: Nomad (Recommended for production)

Distributed deployment with HashiCorp Nomad.

Quick Start

cd spore-deployment

# Start Nomad in dev mode
make nomad-start

# Build Docker images first
cd ../spore-gateway && make docker-build
cd ../spore-ledlab && make docker-build
cd ../spore-registry && make docker-build
cd ../spore-ui && make docker-build

# Deploy the job
make nomad-job-run

# View status
make nomad-status

Services Access

Same ports as Docker Compose deployment.

Nomad UI

Access the Nomad UI at http://localhost:4646 to manage and monitor jobs.

Management

# View Nomad UI
make nomad-ui

# View job logs
make nomad-logs

# Stop the job
make nomad-job-stop

# Restart Nomad
make nomad-stop
make nomad-start

Nomad Configuration

Nomad configuration is in config/nomad/nomad.hcl:

• Dev mode with single agent
• Docker driver enabled
• Host networking for all services
• UI enabled on port 4646

See nomad/README.md for detailed Nomad documentation.

Common Tasks

Building Images

Both deployment methods require Docker images to be built first.

# Using make in each project
cd ../spore-gateway && make docker-build
cd ../spore-ledlab && make docker-build
cd ../spore-registry && make docker-build
cd ../spore-ui && make docker-build

# Or build and push all at once from deployment directory
make push

Building Multiarch Images (amd64 & arm64)

For Raspberry Pi and other ARM devices, build multiarch images:

# One-time setup (run the setup script)
./scripts/setup-multiarch.sh

# Or setup manually:
docker run --rm --privileged tonistiigi/binfmt:latest --install all
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

# Build and push all multiarch images
cd spore-deployment
make push-multiarch

# Or build without pushing
make build-multiarch

# Or build for specific tag
make push-multiarch IMAGE_TAG=v1.0.0

Environment Variables

Docker Compose

Create a .env file to override defaults:

LOG_LEVEL=debug
MATRIX_WIDTH=32
MATRIX_HEIGHT=32
FPS=30

Then run:

docker compose --env-file .env up -d

Nomad

Edit nomad/spore.hcl to modify environment variables or resource allocations.

Data Management

Backup

# Backup all data
tar czf spore-backup.tar.gz ./data/

# Backup registry only
tar czf registry-backup.tar.gz ./data/registry/

Restore

# Restore all data
tar xzf spore-backup.tar.gz

# Restore registry only
tar xzf registry-backup.tar.gz

Reset Data

# Docker Compose
make clean

# Nomad
rm -rf nomad-data/

Logs

Docker Compose

# All services
docker compose logs -f

# Specific service
docker compose logs -f gateway
docker compose logs -f registry

Nomad

# All job logs
make nomad-logs

# Specific task
nomad alloc logs <alloc-id> <task-name>

# Follow logs
nomad alloc logs -f <alloc-id> <task-name>

MQTT Integration

Both deployments enable MQTT integration for the gateway service.

Publishing to MQTT

# Using mosquitto_pub
mosquitto_pub -h localhost -t "spore/cluster/broadcast" -m '{"command":"update"}'

# Send to specific node
mosquitto_pub -h localhost -t "spore/nodes/192.168.1.100/command" -m '{"action":"update"}'

Monitoring MQTT

# Subscribe to all SPORE topics
mosquitto_sub -h localhost -t "spore/#" -v

# Watch specific topic
mosquitto_sub -h localhost -t "spore/cluster/status" -v

MQTT Authentication

Enable authentication by setting environment variables:

Docker Compose:

gateway:
  environment:
    - MQTT_SERVER=tcp://localhost:1883
    - MQTT_USER=username
    - MQTT_PASSWORD=password

Nomad: Edit nomad/spore.hcl to add MQTT_USER and MQTT_PASSWORD env vars.

Troubleshooting

Port Conflicts

If ports are already in use:

Docker Compose: Edit port mappings in docker-compose.yml

Nomad: Edit ports in nomad/spore.hcl

Services Not Starting

Docker Compose:

# Check logs
make logs

# Check container status
docker compose ps

Nomad:

# Check job status
make nomad-status

# Check allocation logs
nomad alloc logs <alloc-id> <task-name>

# Check allocation status
nomad alloc status <alloc-id>

Network Issues

Both deployments use host networking for proper UDP broadcast support. If services can't communicate:

1. Check firewall settings
2. Verify ports are not blocked
3. Check service logs for connection errors

Images Not Found

Ensure Docker images are built before deploying:

# Build all images
make push

# Or build individually
cd ../spore-gateway && make docker-build
cd ../spore-ledlab && make docker-build
cd ../spore-registry && make docker-build
cd ../spore-ui && make docker-build

Production Deployment

Docker Compose

For production, consider:

1. Using environment-specific configuration files
2. Setting up proper logging aggregation
3. Using Docker secrets for sensitive data
4. Implementing health checks
5. Setting resource limits

Nomad

For production deployment:

1. Use a multi-node Nomad cluster
2. Enable ACLs for security
3. Configure TLS for all connections
4. Use external storage for volumes
5. Set up proper monitoring and alerting
6. Configure auto-scaling based on load

Comparing Deployment Options

Feature	Docker Compose	Nomad
Ease of setup	⭐⭐⭐⭐⭐	⭐⭐⭐
Scalability	⭐⭐	⭐⭐⭐⭐⭐
Multi-node	No	Yes
Service discovery	Manual	Built-in
Rolling updates	Manual	Automatic
Resource management	Basic	Advanced
Production-ready	⭐⭐⭐	⭐⭐⭐⭐⭐

Recommendation:

• Use Docker Compose for development, testing, or single-node deployments
• Use Nomad for production, multi-node clusters, or when you need advanced orchestration features

Additional Resources

• SPORE Documentation
• Nomad Deployment Guide
• Docker Compose Documentation
• Nomad Documentation