feat(docker): single-container demo on ubuntu+pixi base, GPU+NPU

Refactor the Docker setup to a single runnable demo container whose entrypoint
is `pixi run demo` — the whole single-pc stack (sim, ROS 2, local inference,
agents, HMI) in one image, mirroring the native demo.

- Layered, cacheable build: ros2 -> o3de -> demo (separately taggable bases).
- Base is ubuntu:24.04, not ros:jazzy-ros-core: RoboStack provides ROS 2 via
  pixi, so the container is pure-pixi (no /opt/ros mixing).
- Dockerfile.demo (new): agents app + llama.cpp (Vulkan) + FastFlowLM fork;
  installs tmux, the lemonade-PPA XRT deps, rustup (tokenizers-cpp) and
  libfftw3-dev (flm link). WITH_NPU build arg gates the NPU build (default 1;
  WITH_NPU=0 for GPU-only).
- compose.yaml: one demo service with /dev/accel/accel0 + /dev/dri + /dev/kfd,
  unlimited memlock (NPU), X11, repo-relative model mount + FLM_MODEL_PATH so
  NPU weights stay under models/ (no host-home coupling), host networking.
- Dockerfile.o3de: refresh apt lists before install-o3de (ros2 base strips them).
- demo.sh: AMM_KEEP_ALIVE holds PID 1 open (attach to tmux on a TTY, else block)
  so the container outlives demo.sh's launch.
- Drop obsolete Dockerfile.agents, Dockerfile.llama, start_sim.sh.
- docs: rewrite quickstart for the local GPU+NPU container flow; fix setup.md
  cross-reference.

Verified: docker compose build is green end-to-end and the demo runs (NPU incl.).

Author: maciejmajek

docker/Dockerfile.agents

@@ -0,0 +1,71 @@
+# Single-PC demo image: the O3DE+ROS 2 base (sim already built) plus the Python
+# agent app and the local inference engines. `pixi run demo` brings the whole
+# stack up in tmux, exactly as on a developer's single-pc machine.
+#
+# base_image = the `o3de` compose service (FROM ros2 -> sim + ROS 2 workspace
+# built, full pixi env already solved). See docker/compose.yaml.
+FROM base_image
+
+WORKDIR /root/MobileManipulatorDemo
+ENV DEMO_ROOT=/root/MobileManipulatorDemo
+
+# Build target. WITH_NPU=1 (default) is the single-pc-gpu-and-npu setup: it builds
+# the FastFlowLM fork for the NPU endpoints. WITH_NPU=0 is GPU-only — llama.cpp
+# (Vulkan) alone — skipping the NPU apt deps and the FastFlowLM compile.
+ARG WITH_NPU=1
+
+# tmux is always required: demo.sh runs each component in its own tmux session.
+RUN apt-get update && apt-get install -y --no-install-recommends tmux \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# NPU build deps (WITH_NPU=1 only). FastFlowLM links the host XRT/NPU libs with
+# the system gcc, not pixi's conda toolchain (see build_fastflowlm.sh): XRT dev
+# headers + the NPU userspace runtime come from the lemonade PPA. The amdxdna
+# *kernel* driver stays on the host; the NPU enters via /dev/accel/accel0.
+RUN if [ "$WITH_NPU" = "1" ]; then \
+        apt-get update && apt-get install -y --no-install-recommends \
+            software-properties-common gnupg \
+     && add-apt-repository -y ppa:lemonade-team/stable \
+     && apt-get update && apt-get install -y --no-install-recommends \
+            build-essential \
+            libxrt-dev libxrt-npu2 \
+            libavformat-dev libavutil-dev libavcodec-dev \
+            libswresample-dev libswscale-dev \
+            libfftw3-dev \
+            uuid-dev libdrm-dev \
+     && apt-get clean && rm -rf /var/lib/apt/lists/* ; \
+    fi
+
+# Python agent app + inference SSOT + RAG corpus + monitoring. Refresh pixi
+# manifests and scripts/ too so this layer's `pixi run` tasks (e.g. the renamed
+# init-submodules) and runtime helpers (demo.sh, ...) match this checkout rather
+# than the snapshot baked into the o3de base.
+COPY pixi.toml pixi.lock ./
+COPY pyproject.toml uv.lock ./
+COPY config.toml ./
+COPY .gitmodules ./
+COPY rai_app/ rai_app/
+COPY regulations_db/ regulations_db/
+COPY monitoring/ monitoring/
+COPY scripts/ scripts/
+RUN pixi run sync
+
+# Local inference engines built from the pinned submodules. llama.cpp (Vulkan,
+# gpu/cpu endpoints) is always built; init-submodules needs .git (inherited from
+# the o3de base) + .gitmodules (copied above).
+RUN pixi run init-submodules && pixi run build-llama
+
+# FastFlowLM (npu endpoints), WITH_NPU=1 only. Its tokenizers-cpp vendors a Rust
+# static lib (libtokenizers_c.a), so the build needs cargo. Install via rustup
+# (latest stable — Ubuntu's apt cargo can be too old for the pinned crate) and
+# source it so cmake's find_program(cargo) succeeds at configure time.
+RUN if [ "$WITH_NPU" = "1" ]; then \
+        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal \
+     && . "$HOME/.cargo/env" \
+     && pixi run build-fastflowlm ; \
+    fi
+
+# Brings up sim -> stack -> inference -> agents -> hmi, one tmux session each.
+# AMM_KEEP_ALIVE (set in compose) holds this process open so the container — and
+# the detached tmux sessions it owns — stay alive after demo.sh finishes launching.
+ENTRYPOINT ["pixi", "run", "demo"]

docker/Dockerfile.demo

@@ -1,7 +1,8 @@
 FROM base_image
 
-# Install O3DE build dependencies and the 26.05 SDK
-# Note: git, git-lfs, ninja-build, ros-dev-tools, pixi are inherited from base image
+# Install O3DE build dependencies and the 26.05 SDK.
+# Note: git, git-lfs, pixi are inherited from the base image; ROS/colcon/cmake/
+# ninja come from the conda env. clang is O3DE's compiler, hence apt here.
 RUN apt update && apt install -y \
     cmake \
     libstdc++-12-dev \
@@ -37,8 +38,11 @@ COPY .git .git/
 COPY project_gems/ project_gems/
 COPY sim/ sim/
 
-RUN pixi run install-o3de
-RUN apt install -y git-lfs && git lfs install --force
+# install_o3de.sh apt-installs the SDK's system deps (ninja-build, pkg-config,
+# ...) without running `apt-get update` itself, so refresh the lists here — the
+# ros2 base strips them to stay small.
+RUN apt-get update && pixi run install-o3de && apt-get clean && rm -rf /var/lib/apt/lists/*
+RUN git lfs install --force
 RUN pixi run build-sim
 
 WORKDIR /root/MobileManipulatorDemo

docker/Dockerfile.llama

@@ -1,20 +1,29 @@
-FROM ros:jazzy-ros-core
-
-RUN apt update && apt install -y --no-install-recommends \
-    curl \
-    python3-vcstool \
-    git \
-    git-lfs \
-    ninja-build \
-    ros-dev-tools \
-    lsb-release \
-    wget \
-    gnupg
-
-RUN wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
-RUN echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
-RUN apt update
-RUN apt install -y libgz-math7-dev
+# RoboStack ships the entire ROS 2 Jazzy runtime through pixi, so the base is
+# plain Ubuntu — NOT ros:jazzy-ros-core. Mixing apt ROS (/opt/ros) with conda
+# RoboStack is exactly what scripts/check_env.sh forbids; an Ubuntu base keeps the
+# container a pure-pixi environment, identical to a native checkout.
+FROM ubuntu:24.04
+
+# colcon/ROS want a UTF-8 locale; C.UTF-8 ships with glibc (no `locales` package).
+ENV LANG=C.UTF-8 LC_ALL=C.UTF-8 DEBIAN_FRONTEND=noninteractive
+
+# Only host-level tooling pixi can't bootstrap itself: the pixi installer plus
+# git/LFS for `vcs import` and submodules. Compilers, colcon, vcstool, cmake and
+# ninja all come from the conda env (see pixi.toml). gz-math is the one system
+# build dep some ros2_ws source packages link against, from the OSRF apt repo.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        wget \
+        git \
+        git-lfs \
+        gnupg \
+        lsb-release \
+ && wget -qO /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg https://packages.osrfoundation.org/gazebo.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" > /etc/apt/sources.list.d/gazebo-stable.list \
+ && apt-get update && apt-get install -y --no-install-recommends \
+        libgz-math7-dev \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
 
 RUN curl -fsSL https://pixi.sh/install.sh | PIXI_HOME=/usr/local bash