@trillboards/edge-sdk 0.2.2 → 0.2.3

package/deploy/docker/README.md

@@ -0,0 +1,358 @@
+# Docker Deployment — Trillboards Edge SDK
+
+This guide covers deploying the Trillboards Edge AI agent as a Docker container for DOOH audience sensing.
+
+## Image Variants
+
+Three pre-built images target different hardware profiles:
+
+| Tag | Base Image | Execution Provider | Architecture | Use Case |
+|-----|-----------|-------------------|--------------|----------|
+| `latest` | `node:20-slim` | CPU (WASM) | `linux/amd64`, `linux/arm64` | Generic Linux devices, ARM SBCs, Raspberry Pi 4+ |
+| `cuda` | `nvidia/cuda:12.3.2-runtime-ubuntu22.04` | NVIDIA CUDA | `linux/amd64` | NVIDIA Jetson, GPU-equipped signage players |
+| `openvino` | `openvino/ubuntu22_runtime:2024.0.0` | Intel OpenVINO | `linux/amd64` | Backpackster, Intel NUC, mini-PCs with Intel HD 620+ |
+
+## Registry Locations
+
+Images are published to two registries. Use whichever is reachable from your deployment environment.
+
+**GitHub Container Registry (public):**
+
+```bash
+docker pull ghcr.io/trillboards/edge-sdk:latest
+docker pull ghcr.io/trillboards/edge-sdk:cuda
+docker pull ghcr.io/trillboards/edge-sdk:openvino
+```
+
+**AWS ECR (private, for production fleet):**
+
+```bash
+aws ecr get-login-password --region us-east-1 | \
+  docker login --username AWS --password-stdin 975050306809.dkr.ecr.us-east-1.amazonaws.com
+
+docker pull 975050306809.dkr.ecr.us-east-1.amazonaws.com/trillboards-edge-sdk:latest
+docker pull 975050306809.dkr.ecr.us-east-1.amazonaws.com/trillboards-edge-sdk:cuda
+docker pull 975050306809.dkr.ecr.us-east-1.amazonaws.com/trillboards-edge-sdk:openvino
+```
+
+## Quick Start
+
+```bash
+docker run -d \
+  --name trillboards-edge \
+  -e DEVICE_TOKEN=your_device_token_here \
+  -p 9090:9090 \
+  ghcr.io/trillboards/edge-sdk:latest
+```
+
+Obtain your `DEVICE_TOKEN` from the Trillboards dashboard under **Devices > Add Device**.
+
+## Environment Variables
+
+All configuration is driven through environment variables. The container entrypoint generates a config JSON from these at startup.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEVICE_TOKEN` | *(required)* | Authentication token for backend API registration. Get this from your Trillboards dashboard. |
+| `API_BASE_URL` | `https://api.trillboards.com` | Backend API endpoint. Override for staging or self-hosted deployments. |
+| `CAMERA_ENABLED` | `false` | Enable camera capture for face detection. Requires `/dev/video*` device passthrough. |
+| `AUDIO_ENABLED` | `false` | Enable audio capture for ambient classification (YAMNet). Requires ALSA/PulseAudio access. |
+| `KIOSK_ENABLED` | `false` | Launch a headless Chromium browser pointing to the Trillboards screen player. |
+| `EXECUTION_PROVIDER` | `cpu` (CPU image), `cuda` (CUDA image), `openvino` (OpenVINO image) | ONNX Runtime execution provider. One of: `cpu`, `cuda`, `openvino`, `directml`. |
+| `STATUS_PORT` | `9090` | HTTP port for the local status server (`/status`, `/health`, `/metrics`). |
+| `LOG_LEVEL` | `info` | Logging verbosity. One of: `debug`, `info`, `warn`, `error`. |
+| `MODELS_DIR` | `/app/models` | Directory containing ONNX model files (`blazeface.onnx`, `yamnet.onnx`). |
+| `DATA_DIR` | `/app/data` | Persistence directory for signal buffer, device identity, and federated learning state. |
+| `SCREEN_ID` | *(empty)* | Override the screen identifier. If empty, the agent registers automatically with the backend. |
+| `VENUE_TYPE` | *(empty)* | Venue classification string (e.g., `retail`, `transit`, `office`). Used for contextual audience grading. |
+
+## docker-compose Example
+
+```yaml
+version: "3.8"
+
+services:
+  trillboards-edge:
+    image: ghcr.io/trillboards/edge-sdk:latest
+    container_name: trillboards-edge
+    restart: unless-stopped
+    environment:
+      DEVICE_TOKEN: "${DEVICE_TOKEN}"
+      API_BASE_URL: "https://api.trillboards.com"
+      CAMERA_ENABLED: "true"
+      AUDIO_ENABLED: "true"
+      KIOSK_ENABLED: "false"
+      EXECUTION_PROVIDER: "cpu"
+      LOG_LEVEL: "info"
+    ports:
+      - "9090:9090"
+    volumes:
+      # Persist signal buffer and device identity across restarts
+      - trillboards-data:/app/data
+      # Persist downloaded models to avoid re-downloading on restart
+      - trillboards-models:/app/models
+      # Camera device passthrough (Linux only)
+      - /dev:/dev:ro
+    devices:
+      - /dev/video0:/dev/video0
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 30s
+      retries: 3
+
+volumes:
+  trillboards-data:
+  trillboards-models:
+```
+
+Start the stack:
+
+```bash
+DEVICE_TOKEN=your_token docker compose up -d
+```
+
+## GPU Passthrough (NVIDIA CUDA)
+
+The CUDA image requires the NVIDIA Container Toolkit.
+
+**Install the runtime:**
+
+```bash
+# Ubuntu/Debian
+distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
+  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
+  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+**Run with GPU access:**
+
+```bash
+docker run -d \
+  --name trillboards-edge-cuda \
+  --gpus all \
+  -e DEVICE_TOKEN=your_token \
+  -e CAMERA_ENABLED=true \
+  -p 9090:9090 \
+  -v trillboards-data:/app/data \
+  -v trillboards-models:/app/models \
+  ghcr.io/trillboards/edge-sdk:cuda
+```
+
+**docker-compose with GPU:**
+
+```yaml
+services:
+  trillboards-edge:
+    image: ghcr.io/trillboards/edge-sdk:cuda
+    environment:
+      DEVICE_TOKEN: "${DEVICE_TOKEN}"
+      CAMERA_ENABLED: "true"
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    ports:
+      - "9090:9090"
+    volumes:
+      - trillboards-data:/app/data
+      - trillboards-models:/app/models
+```
+
+The CUDA image sets `NVIDIA_VISIBLE_DEVICES=all` and `NVIDIA_DRIVER_CAPABILITIES=compute,utility` automatically.
+
+## Volume Mounts
+
+Two directories should be persisted across container restarts:
+
+| Mount Point | Purpose | Contents |
+|-------------|---------|----------|
+| `/app/models` | ONNX model files | `blazeface.onnx`, `yamnet.onnx`, and any OTA-updated models |
+| `/app/data` | Agent persistent state | `signal_buffer.db` (SQLite signal buffer), device identity fingerprint, federated learning gradients |
+
+Default models (`blazeface.onnx` and `yamnet.onnx`) are downloaded at image build time from `https://models.trillboards.com/`. If you mount an empty volume, the agent will operate without models until they are downloaded or placed manually.
+
+**Pre-populating models on the host:**
+
+```bash
+mkdir -p /opt/trillboards/models
+curl -o /opt/trillboards/models/blazeface.onnx https://models.trillboards.com/blazeface_128x128.onnx
+curl -o /opt/trillboards/models/yamnet.onnx https://models.trillboards.com/yamnet_classification.onnx
+```
+
+Then mount as a bind volume:
+
+```bash
+docker run -d \
+  -e DEVICE_TOKEN=your_token \
+  -v /opt/trillboards/models:/app/models \
+  -v /opt/trillboards/data:/app/data \
+  ghcr.io/trillboards/edge-sdk:latest
+```
+
+## Health Check Configuration
+
+The container includes a built-in `HEALTHCHECK` that probes the local status server:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:9090/health || exit 1
+```
+
+The `/health` endpoint returns:
+- **200 OK** with `{"status":"ok"}` when all subsystems are healthy
+- **503 Service Unavailable** with `{"status":"degraded","failed":["CAMERA","SOCKET"]}` when one or more subsystems are in an error state
+
+Docker reports the container as `healthy`, `unhealthy`, or `starting` based on this probe.
+
+To verify manually:
+
+```bash
+docker inspect --format='{{.State.Health.Status}}' trillboards-edge
+```
+
+## Building Custom Images
+
+All Dockerfiles use multi-stage builds. The build context must be the monorepo root (`trillboards-edge-sdk/`).
+
+**CPU image:**
+
+```bash
+cd trillboards-edge-sdk
+docker build -f packages/edge-sdk/deploy/docker/Dockerfile.cpu \
+  -t trillboards/edge-sdk:latest .
+```
+
+**CUDA image:**
+
+```bash
+cd trillboards-edge-sdk
+docker build -f packages/edge-sdk/deploy/docker/Dockerfile.cuda \
+  -t trillboards/edge-sdk:cuda .
+```
+
+**OpenVINO image:**
+
+```bash
+cd trillboards-edge-sdk
+docker build -f packages/edge-sdk/deploy/docker/Dockerfile.openvino \
+  -t trillboards/edge-sdk:openvino .
+```
+
+### Build Arguments
+
+The Dockerfiles do not expose build arguments by default. To customize the build (for example, to pin a specific Node.js version or add additional system packages), edit the relevant Dockerfile directly.
+
+### Multi-Architecture Builds (CPU Image Only)
+
+The CPU image supports `linux/amd64` and `linux/arm64` via Docker Buildx:
+
+```bash
+docker buildx create --use
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -f packages/edge-sdk/deploy/docker/Dockerfile.cpu \
+  -t ghcr.io/trillboards/edge-sdk:latest \
+  --push .
+```
+
+The CUDA and OpenVINO images are `linux/amd64` only due to base image constraints.
+
+## Camera Device Passthrough
+
+For face detection, the container needs access to the host camera device.
+
+**USB camera on Linux:**
+
+```bash
+docker run -d \
+  --device /dev/video0:/dev/video0 \
+  -e DEVICE_TOKEN=your_token \
+  -e CAMERA_ENABLED=true \
+  ghcr.io/trillboards/edge-sdk:latest
+```
+
+**Multiple cameras:**
+
+```bash
+docker run -d \
+  --device /dev/video0 \
+  --device /dev/video2 \
+  -e DEVICE_TOKEN=your_token \
+  -e CAMERA_ENABLED=true \
+  ghcr.io/trillboards/edge-sdk:latest
+```
+
+**Privileged mode (not recommended, but required for some RTSP setups):**
+
+```bash
+docker run -d \
+  --privileged \
+  -e DEVICE_TOKEN=your_token \
+  -e CAMERA_ENABLED=true \
+  ghcr.io/trillboards/edge-sdk:latest
+```
+
+## Networking
+
+The container exposes a single port:
+
+| Port | Protocol | Endpoint | Purpose |
+|------|----------|----------|---------|
+| 9090 | HTTP | `/status`, `/health`, `/metrics` | Local status server for monitoring, health checks, and Prometheus scraping |
+
+Outbound connectivity is required to:
+- `api.trillboards.com:443` (HTTPS) -- REST API and Socket.io
+- `models.trillboards.com:443` (HTTPS) -- OTA model downloads (optional, only during model updates)
+
+## Logging
+
+Logs are written to stdout/stderr in structured format:
+
+```
+[2026-03-16T14:30:00.000Z] [INFO] Starting Trillboards Edge Agent v0.2.2
+[2026-03-16T14:30:00.050Z] [INFO] Platform adapter loaded: linux
+[2026-03-16T14:30:00.100Z] [INFO] Device fingerprint: abc123def456
+[2026-03-16T14:30:00.150Z] [INFO] Capability tier: TIER_2 (...)
+```
+
+Use `LOG_LEVEL=debug` for verbose output during troubleshooting. In production, `info` is sufficient.
+
+View logs:
+
+```bash
+docker logs -f trillboards-edge
+```
+
+## Troubleshooting
+
+**Container exits immediately:**
+- Check that `DEVICE_TOKEN` is set and valid. The agent throws an error at startup if the token is empty.
+- Verify API connectivity: `docker run --rm ghcr.io/trillboards/edge-sdk:latest curl -s https://api.trillboards.com/health/live`
+
+**Health check fails:**
+- The status server takes up to 30 seconds to start (matching the `start_period` in the health check).
+- Check logs for initialization errors: `docker logs trillboards-edge`
+
+**Camera not detected:**
+- Verify the host device exists: `ls -la /dev/video*`
+- Pass the device explicitly: `--device /dev/video0`
+- Check permissions inside the container: `docker exec trillboards-edge ls -la /dev/video0`
+
+**CUDA not available:**
+- Verify the NVIDIA runtime is installed: `docker run --rm --gpus all nvidia/cuda:12.3.2-runtime-ubuntu22.04 nvidia-smi`
+- Ensure you are using the `cuda` tag, not `latest`
+
+**Models not found:**
+- Models are downloaded at image build time. If the build had no network access, models will be missing.
+- Mount a volume with pre-downloaded models at `/app/models`
+- Or download inside the container: `docker exec trillboards-edge node -e "..." ` (see Dockerfile for the download script)