Fix Pi standalone startup and ONNX model pin

248Tech · 248Tech · commit 793a239a0336 · 2026-03-19T16:46:06.000-04:00
diff --git a/README.md b/README.md
@@ -98,7 +98,8 @@ chmod +x ./scripts/pi-*.sh
 Equivalent manual command:
 
 ```bash
-docker compose --profile pi up --build -d rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi build rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi up -d --no-build rtspanda-pi
 ```
 
 Behavior:
@@ -122,7 +123,8 @@ Best for a distributed deployment where the Pi handles cameras and the second ma
 ```bash
 git clone https://github.com/248Tech/RTSPanda.git
 cd RTSPanda
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 Verify the worker:
@@ -144,7 +146,8 @@ export AI_WORKER_URL="http://192.168.1.50:8090"
 Equivalent manual command on the Pi:
 
 ```bash
-docker compose --profile pi up --build -d rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi build rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi up -d --no-build rtspanda-pi
 ```
 
 Verify from the Pi:
@@ -165,14 +168,14 @@ The Docker AI worker is ONNX-only and never exports or converts models at runtim
 
 ```bash
 export MODEL_SOURCE=remote
-export YOLO_MODEL_NAME=yolov8n
+export YOLO_MODEL_NAME=yolo11n
 export YOLO_MODEL_RELEASE=v8.3.0
 ```
 
 Optional mirror:
 
 ```bash
-export YOLO_MODEL_URL="https://your-mirror.example/yolov8n.onnx"
+export YOLO_MODEL_URL="https://your-mirror.example/yolo11n.onnx"
 ```
 
 ### Local prebuilt model
diff --git a/RELEASE_NOTES_v0.0.8.md b/RELEASE_NOTES_v0.0.8.md
@@ -9,24 +9,29 @@ RTSPanda v0.0.8 turns the project into a more serious edge-video platform: the d
 - Removed AI-worker export fallback from Docker builds. The worker now uses prebuilt ONNX models only.
 - Added additive Compose profiles for `full`, `pi`, and `ai-worker` without breaking the existing `docker compose up --build -d` flow.
 - Rewrote setup and deployment docs to clearly support Standard, Pi Standalone, and Pi + AI topologies.
+- Fixed Pi standalone startup so it no longer traverses the local AI-worker build path.
+- Repaired the default remote ONNX pin to a live Ultralytics asset and improved failure messages for invalid model sources.
 
 ## What Changed
 ### Platform and Deployment
 - `docker-compose.yml` now supports:
   - standard full-stack deployment
   - lightweight Pi deployment
   - standalone remote AI-worker deployment
+- New `docker-compose.standalone.yml` overlay isolates Pi-only and AI-worker-only deployments from the unprofiled full stack.
 - `scripts/pi-up.sh` now supports:
   - `PI_DEPLOYMENT_MODE=pi`
   - `PI_DEPLOYMENT_MODE=full`
   - `PI_DEPLOYMENT_MODE=ai-worker`
+- Standalone launch paths now use `build` followed by `up --no-build` so targeted deployments only build the intended service.
 - `scripts/pi-preflight.sh` now checks deployment mode and model-source expectations more accurately for Docker-first Pi workflows.
 
 ### AI Runtime
 - `ai_worker/Dockerfile` now resolves models deterministically:
   - local prebuilt ONNX file first
   - explicit `YOLO_MODEL_URL` second
   - named Ultralytics ONNX asset fallback last
+- Default remote model pin now targets `yolo11n` on Ultralytics `v8.3.0`, which is published and buildable today.
 - No PyTorch install path
 - No `YOLO(...).export(...)`
 - No runtime model conversion on ARM
@@ -60,7 +65,8 @@ docker compose up --build -d
 AI host:
 
 ```bash
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 Pi host:
diff --git a/ai_worker/Dockerfile b/ai_worker/Dockerfile
@@ -13,7 +13,7 @@
 FROM python:3.12-slim AS model-resolver
 
 ARG MODEL_SOURCE=remote
-ARG YOLO_MODEL_NAME=yolov8n
+ARG YOLO_MODEL_NAME=yolo11n
 ARG YOLO_MODEL_RELEASE=v8.3.0
 ARG YOLO_MODEL_URL
 
@@ -41,13 +41,13 @@ RUN --mount=type=bind,source=.,target=/context,readonly \
       exit 1; \
     elif [ -n "${YOLO_MODEL_URL:-}" ]; then \
       curl -fsSL "${YOLO_MODEL_URL}" -o /model/model.onnx || { \
-        echo "failed to download model from YOLO_MODEL_URL=${YOLO_MODEL_URL}" >&2; exit 1; \
+        echo "failed to download model from YOLO_MODEL_URL=${YOLO_MODEL_URL}; provide a valid URL or use MODEL_SOURCE=local with ./model.onnx" >&2; exit 1; \
       }; \
     else \
       model_file="${YOLO_MODEL_NAME}.onnx"; \
       model_url="https://github.com/ultralytics/assets/releases/download/${YOLO_MODEL_RELEASE}/${model_file}"; \
       curl -fsSL "${model_url}" -o /model/model.onnx || { \
-        echo "failed to download prebuilt ONNX model ${model_file} from ${model_url}" >&2; exit 1; \
+        echo "failed to download prebuilt ONNX model ${model_file} from ${model_url}; set YOLO_MODEL_URL or provide ./model.onnx / ./ai_worker/model/model.onnx" >&2; exit 1; \
       }; \
     fi; \
     test -s /model/model.onnx
diff --git a/ai_worker/export_model.py b/ai_worker/export_model.py
@@ -1,15 +1,15 @@
 """
-Export a YOLOv8 .pt model to ONNX format for use with the RTSPanda AI worker.
+Export a YOLO .pt model to ONNX format for use with the RTSPanda AI worker.
 
 Usage (run once, requires ultralytics):
 
     pip install ultralytics
     python ai_worker/export_model.py
-    # produces ai_worker/yolov8n.onnx
+    # produces ai_worker/yolo11n.onnx
 
 Then point the AI worker at the file:
 
-    YOLO_MODEL_PATH=/path/to/yolov8n.onnx uvicorn app.main:app ...
+    YOLO_MODEL_PATH=/path/to/yolo11n.onnx uvicorn app.main:app ...
 
 For Docker users, export the model ahead of time and either:
 - place it at ./model.onnx before building the image, or
@@ -47,11 +47,11 @@ def export(model_name: str, output_dir: Path) -> Path:
 
 
 if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Export YOLOv8 model to ONNX")
+    parser = argparse.ArgumentParser(description="Export YOLO model to ONNX")
     parser.add_argument(
         "--model",
-        default="yolov8n",
-        help="Model name without extension, e.g. yolov8n, yolov8s (default: yolov8n)",
+        default="yolo11n",
+        help="Model name without extension, e.g. yolo11n, yolo11s (default: yolo11n)",
     )
     parser.add_argument(
         "--output-dir",
diff --git a/docker-compose.standalone.yml b/docker-compose.standalone.yml
@@ -0,0 +1,11 @@
+# Standalone-mode compose overlay.
+#
+# Use this file together with docker-compose.yml for Pi-only or AI-worker-only
+# deployments so unprofiled full-stack services do not remain active in the
+# combined project model.
+services:
+  ai-worker:
+    profiles: ["full"]
+
+  rtspanda:
+    profiles: ["full"]
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -4,7 +4,7 @@ x-ai-worker-common: &ai-worker-common
     dockerfile: ai_worker/Dockerfile
     args:
       MODEL_SOURCE: ${MODEL_SOURCE:-remote}
-      YOLO_MODEL_NAME: ${YOLO_MODEL_NAME:-yolov8n}
+      YOLO_MODEL_NAME: ${YOLO_MODEL_NAME:-yolo11n}
       YOLO_MODEL_RELEASE: ${YOLO_MODEL_RELEASE:-v8.3.0}
       YOLO_MODEL_URL: ${YOLO_MODEL_URL:-}
   image: rtspanda-ai-worker:latest
diff --git a/docs/ai-pi-compatibility.md b/docs/ai-pi-compatibility.md
@@ -37,7 +37,7 @@ The worker now includes explicit low-power controls:
 
 ## 3) CPU-Only Inference Expectations (Realistic)
 
-These are practical planning ranges for **YOLOv8n ONNX** on CPU-only Pi, assuming one worker and no GPU/NPU acceleration:
+These are practical planning ranges for a **nano-class ONNX detector such as `yolo11n`** on CPU-only Pi, assuming one worker and no GPU/NPU acceleration:
 
 - **Pi 5 (8 GB)**, 640 input: typically **~250-450 ms/inference** (about 2-4 FPS max sustained detector throughput).
 - **Pi 4 (4-8 GB)**, 640 input: typically **~600-1200 ms/inference** (about 0.8-1.6 FPS).
@@ -47,7 +47,7 @@ Operational guidance:
 
 - For backend sampling, plan around **1 frame every 1-3 seconds per actively tracked camera** on Pi 4.
 - Use **single detector concurrency** and keep queue depth low.
-- Prefer `yolov8n` for Pi; larger variants (`s/m/l/x`) are usually too slow for practical multi-camera tracking.
+- Prefer `yolo11n` for Pi; larger variants (`s/m/l/x`) are usually too slow for practical multi-camera tracking.
 
 ## 4) Frame Processing Limits and Tunables
 
@@ -106,7 +106,7 @@ This keeps API compatibility while disabling heavy inference entirely.
 
 ## 6) Recommended Model/Runtime Adjustments
 
-- Prefer **YOLOv8n ONNX**.
+- Prefer **YOLO11n ONNX**.
 - Keep backend detection sampling conservative (seconds, not sub-second) on Pi.
 - Keep detector concurrency at 1 where possible.
 - Avoid large source frames; downscale before inference.
diff --git a/docs/cluster-mode.md b/docs/cluster-mode.md
@@ -24,7 +24,8 @@ The transport stays simple:
 ```bash
 git clone https://github.com/248Tech/RTSPanda.git
 cd RTSPanda
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 Health check:
@@ -50,7 +51,8 @@ export AI_WORKER_URL="http://192.168.1.50:8090"
 Equivalent manual command:
 
 ```bash
-docker compose --profile pi up --build -d rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi build rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi up -d --no-build rtspanda-pi
 ```
 
 ## 3. Verify the connection
@@ -76,21 +78,23 @@ Expected:
 
 ```bash
 export MODEL_SOURCE=remote
-export YOLO_MODEL_NAME=yolov8n
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+export YOLO_MODEL_NAME=yolo11n
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 ### Use a local prebuilt model
 
 ```bash
 cp /path/to/model.onnx ./model.onnx
 export MODEL_SOURCE=local
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 You can also place the file at `./ai_worker/model/model.onnx`.
 
 ## Operational Notes
 - Keep the AI host and Pi on a stable LAN.
-- Prefer `yolov8n` for CPU-only deployments unless you have measured headroom.
+- Prefer `yolo11n` for CPU-only deployments unless you have measured headroom.
 - The default `docker compose up --build -d` workflow is unchanged and still runs the full local stack on a single machine.
diff --git a/docs/raspberry-pi-deployment.md b/docs/raspberry-pi-deployment.md
@@ -33,7 +33,8 @@ PI_DEPLOYMENT_MODE=ai-worker ./scripts/pi-up.sh
 Or directly:
 
 ```bash
-docker compose --profile ai-worker up --build -d ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker build ai-worker-standalone
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile ai-worker up -d --no-build ai-worker-standalone
 ```
 
 ## Upgrades
diff --git a/docs/raspberry-pi.md b/docs/raspberry-pi.md
@@ -27,7 +27,8 @@ chmod +x ./scripts/pi-*.sh
 This is equivalent to:
 
 ```bash
-docker compose --profile pi up --build -d rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi build rtspanda-pi
+docker compose -f docker-compose.yml -f docker-compose.standalone.yml --profile pi up -d --no-build rtspanda-pi
 ```
 
 If `AI_WORKER_URL` is not set, the Pi stays usable for RTSP ingestion, playback, and recording while detection health remains degraded.
@@ -65,14 +66,14 @@ Default behavior:
 
 ```bash
 export MODEL_SOURCE=remote
-export YOLO_MODEL_NAME=yolov8n
+export YOLO_MODEL_NAME=yolo11n
 export YOLO_MODEL_RELEASE=v8.3.0
 ```
 
 Optional explicit URL:
 
 ```bash
-export YOLO_MODEL_URL="https://your-mirror.example/yolov8n.onnx"
+export YOLO_MODEL_URL="https://your-mirror.example/yolo11n.onnx"
 ```
 
 ### Local model baked into the image
diff --git a/scripts/pi-up.sh b/scripts/pi-up.sh
@@ -7,6 +7,7 @@ ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
 PI_DEPLOYMENT_MODE="${PI_DEPLOYMENT_MODE:-pi}"
 APP_URL="${APP_URL:-http://127.0.0.1:8080}"
 AI_WORKER_HEALTH_URL="${AI_WORKER_HEALTH_URL:-http://127.0.0.1:8090/health}"
+COMPOSE_FILES="-f docker-compose.yml"
 COMPOSE_PROFILE=""
 COMPOSE_SERVICES=""
 
@@ -20,6 +21,7 @@ fail() {
 select_mode() {
   case "$PI_DEPLOYMENT_MODE" in
     pi)
+      COMPOSE_FILES="$COMPOSE_FILES -f docker-compose.standalone.yml"
       COMPOSE_PROFILE="--profile pi"
       COMPOSE_SERVICES="rtspanda-pi"
       if [ -z "${AI_WORKER_URL:-}" ] && [ -z "${DETECTOR_URL:-}" ]; then
@@ -30,6 +32,7 @@ select_mode() {
       COMPOSE_SERVICES="rtspanda ai-worker"
       ;;
     ai-worker)
+      COMPOSE_FILES="$COMPOSE_FILES -f docker-compose.standalone.yml"
       COMPOSE_PROFILE="--profile ai-worker"
       COMPOSE_SERVICES="ai-worker-standalone"
       ;;
@@ -58,19 +61,19 @@ require_docker() {
 compose_up() {
   cd "$ROOT_DIR"
   info "validating docker compose configuration"
-  if [ -n "$COMPOSE_PROFILE" ]; then
-    # shellcheck disable=SC2086
-    docker compose $COMPOSE_PROFILE config -q || fail "docker compose config validation failed"
-    info "building and starting $COMPOSE_SERVICES"
-    # shellcheck disable=SC2086
-    docker compose $COMPOSE_PROFILE up --build -d $COMPOSE_SERVICES || fail "docker compose up failed"
-  else
-    docker compose config -q || fail "docker compose config validation failed"
-    info "building and starting $COMPOSE_SERVICES"
-    # shellcheck disable=SC2086
-    docker compose up --build -d $COMPOSE_SERVICES || fail "docker compose up failed"
-  fi
-  docker compose ps
+  # shellcheck disable=SC2086
+  docker compose $COMPOSE_FILES $COMPOSE_PROFILE config -q || fail "docker compose config validation failed"
+
+  info "building $COMPOSE_SERVICES"
+  # shellcheck disable=SC2086
+  docker compose $COMPOSE_FILES $COMPOSE_PROFILE build $COMPOSE_SERVICES || fail "docker compose build failed"
+
+  info "starting $COMPOSE_SERVICES"
+  # shellcheck disable=SC2086
+  docker compose $COMPOSE_FILES $COMPOSE_PROFILE up -d --no-build $COMPOSE_SERVICES || fail "docker compose up failed"
+
+  # shellcheck disable=SC2086
+  docker compose $COMPOSE_FILES ps
 }
 
 wait_for_url() {
@@ -124,20 +127,20 @@ print_next_steps() {
     ai-worker)
       info "standalone AI worker deployment completed"
       printf "Health: %s\n" "$AI_WORKER_HEALTH_URL"
-      printf "Logs: docker compose logs -f ai-worker-standalone\n"
+      printf "Logs: docker compose %s logs -f ai-worker-standalone\n" "$COMPOSE_FILES"
       ;;
     pi)
       info "Pi lightweight deployment completed"
       printf "Open: %s\n" "$APP_URL"
-      printf "Logs: docker compose logs -f rtspanda-pi\n"
+      printf "Logs: docker compose %s logs -f rtspanda-pi\n" "$COMPOSE_FILES"
       ;;
     full)
       info "full Pi deployment completed"
       printf "Open: %s\n" "$APP_URL"
-      printf "Logs: docker compose logs -f rtspanda ai-worker\n"
+      printf "Logs: docker compose %s logs -f rtspanda ai-worker\n" "$COMPOSE_FILES"
       ;;
   esac
-  printf "Stop: docker compose down\n"
+  printf "Stop: docker compose %s down\n" "$COMPOSE_FILES"
 }
 
 select_mode
