fix(demos): auto-headless when no display (macOS, headless hosts)

The GUI run mode launched the Gazebo/RViz client even with no X
server, which aborts the whole required launch on macOS Docker
Desktop. Detect a missing DISPLAY and fall back to headless, printing
what still works (REST API, Web UI). Covers turtlebot3 and moveit.

Author: mfaferek93

README.md

@@ -87,7 +87,7 @@ Full mobile robot demo with autonomous navigation:
 ```bash
 cd demos/turtlebot3_integration
 ./run-demo.sh
-# Gazebo will open, Web UI at http://localhost:3000
+# Gazebo will open (on macOS / headless hosts it runs headless automatically), Web UI at http://localhost:3000
 # Try: ./send-nav-goal.sh 2.0 0.5
 
 # To stop

demos/moveit_pick_place/run-demo.sh

@@ -38,7 +38,7 @@ trap cleanup EXIT
 # Parse arguments
 COMPOSE_ARGS=""
 BUILD_ARGS=""
-HEADLESS_MODE="false"
+HEADLESS_MODE="${HEADLESS:-false}"
 UPDATE_IMAGES="false"
 DETACH_MODE="true"
 
@@ -102,6 +102,23 @@ if [[ -z "$COMPOSE_ARGS" ]]; then
     COMPOSE_ARGS="--profile cpu"
 fi
 
+# Auto-enable headless when there is no display to render the RViz/Gazebo GUI.
+# macOS Docker Desktop has no X server, and headless Linux hosts have no DISPLAY;
+# in both cases the GUI cannot open and would abort the launch.
+# An explicit --headless (or HEADLESS=true) always wins.
+if [[ "$HEADLESS_MODE" != "true" && -z "${DISPLAY:-}" ]]; then
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        echo "ℹ️  macOS detected with no X display: running HEADLESS."
+        echo "    Docker Desktop on macOS cannot open the RViz/Gazebo window."
+    else
+        echo "ℹ️  No DISPLAY detected: running HEADLESS (no GUI window)."
+    fi
+    echo "    MoveIt planning and ros2_medkit still run normally:"
+    echo "      REST API -> http://localhost:8080/api/v1/"
+    echo "      Web UI   -> http://localhost:3000/"
+    HEADLESS_MODE="true"
+fi
+
 # Export for docker-compose
 export HEADLESS=$HEADLESS_MODE
 export LAUNCH_FILE="demo_gazebo.launch.py"

demos/turtlebot3_integration/README.md

@@ -23,7 +23,7 @@ This demo demonstrates:
 ## Prerequisites
 
 - Docker and docker-compose
-- X11 display server (Linux with GUI, or XQuartz on macOS)
+- (Optional) X11 display server for the Gazebo GUI on Linux with a desktop. Not needed on macOS or headless hosts - the demo falls back to headless automatically.
 - (Optional) NVIDIA GPU + [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
 - `curl` and `jq` (required for host-side scripts)
 
@@ -45,6 +45,8 @@ That's it! The script will:
 
 **Note:** By default, the demo runs in **daemon mode** with **Gazebo GUI** enabled. This allows you to interact with ROS 2 while the demo is running.
 
+**On macOS:** Docker Desktop has no X server, so `run-demo.sh` detects this and starts **headless automatically** - no XQuartz needed. The Gazebo 3D window is not shown, but the simulation, Nav2, ros2_medkit, the REST API (`http://localhost:8080`) and the Web UI (`http://localhost:3000`) all run. Drive the demo from the Web UI and the helper scripts (`./send-nav-goal.sh`, fault injection). The same auto-fallback applies to any host without a `DISPLAY` (for example a headless Linux server).
+
 ### Available Options
 
 ```bash

demos/turtlebot3_integration/run-demo-debounce.sh

@@ -30,23 +30,20 @@ if ! command -v docker &> /dev/null; then
     exit 1
 fi
 
-# Setup X11 forwarding for GUI (Gazebo)
-echo "Setting up X11 forwarding..."
-xhost +local:docker 2>/dev/null || {
-    echo "   Warning: xhost failed. GUI may not work."
-}
-
-# Cleanup function
+# Cleanup function (undo the X11 grant only if we actually set it up)
+X11_FORWARDING="false"
 cleanup() {
     echo ""
     echo "Cleaning up..."
-    xhost -local:docker 2>/dev/null || true
+    if [[ "$X11_FORWARDING" == "true" ]]; then
+        xhost -local:docker 2>/dev/null || true
+    fi
     echo "Done!"
 }
 trap cleanup EXIT
 
 # Parse arguments
-HEADLESS_MODE="false"
+HEADLESS_MODE="${HEADLESS:-false}"
 DETACH_MODE="true"
 PROFILE="cpu"
 
@@ -60,6 +57,33 @@ while [[ $# -gt 0 ]]; do
     shift
 done
 
+# Auto-enable headless when there is no display to render the Gazebo GUI.
+# macOS Docker Desktop has no X server, and headless Linux hosts have no DISPLAY;
+# in both cases the Gazebo window cannot open and would abort the whole launch.
+# An explicit --headless (or HEADLESS=true) always wins.
+if [[ "$HEADLESS_MODE" != "true" && -z "${DISPLAY:-}" ]]; then
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        echo "ℹ️  macOS detected with no X display: running HEADLESS."
+        echo "    Docker Desktop on macOS cannot open the Gazebo 3D window."
+    else
+        echo "ℹ️  No DISPLAY detected: running HEADLESS (no Gazebo 3D window)."
+    fi
+    echo "    The simulation and ros2_medkit still run normally:"
+    echo "      REST API -> http://localhost:8080/api/v1/"
+    echo "      Web UI   -> http://localhost:3000/"
+    HEADLESS_MODE="true"
+fi
+
+# Set up X11 forwarding only when a GUI will actually be shown
+if [[ "$HEADLESS_MODE" != "true" ]]; then
+    echo "Setting up X11 forwarding..."
+    if xhost +local:docker 2>/dev/null; then
+        X11_FORWARDING="true"
+    else
+        echo "   Warning: xhost failed. GUI may not work."
+    fi
+fi
+
 export HEADLESS=$HEADLESS_MODE
 
 DETACH_FLAG=""

demos/turtlebot3_integration/run-demo.sh

@@ -21,26 +21,22 @@ if ! command -v docker &> /dev/null; then
     exit 1
 fi
 
-# Setup X11 forwarding for GUI (Gazebo, RViz)
-echo "Setting up X11 forwarding..."
-xhost +local:docker 2>/dev/null || {
-    echo "   Warning: xhost failed. GUI may not work."
-    echo "   Install with: sudo apt install x11-xserver-utils"
-}
-
-# Cleanup function
+# Cleanup function (undo the X11 grant only if we actually set it up)
+X11_FORWARDING="false"
 cleanup() {
     echo ""
     echo "Cleaning up..."
-    xhost -local:docker 2>/dev/null || true
+    if [[ "$X11_FORWARDING" == "true" ]]; then
+        xhost -local:docker 2>/dev/null || true
+    fi
     echo "Done!"
 }
 trap cleanup EXIT
 
 # Parse arguments
 COMPOSE_ARGS=""
 BUILD_ARGS=""
-HEADLESS_MODE="false"
+HEADLESS_MODE="${HEADLESS:-false}"
 UPDATE_IMAGES="false"
 DETACH_MODE="true"
 
@@ -107,6 +103,35 @@ if [[ -z "$COMPOSE_ARGS" ]]; then
     COMPOSE_ARGS="--profile cpu"
 fi
 
+# Auto-enable headless when there is no display to render the Gazebo GUI.
+# macOS Docker Desktop has no X server, and headless Linux hosts have no DISPLAY;
+# in both cases the Gazebo window cannot open and would abort the whole launch.
+# An explicit --headless (or HEADLESS=true) always wins.
+if [[ "$HEADLESS_MODE" != "true" && -z "${DISPLAY:-}" ]]; then
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        echo "ℹ️  macOS detected with no X display: running HEADLESS."
+        echo "    Docker Desktop on macOS cannot open the Gazebo 3D window."
+    else
+        echo "ℹ️  No DISPLAY detected: running HEADLESS (no Gazebo 3D window)."
+    fi
+    echo "    The simulation, Nav2 and ros2_medkit still run normally:"
+    echo "      REST API -> http://localhost:8080/api/v1/"
+    echo "      Web UI   -> http://localhost:3000/"
+    echo "    You can still send nav goals and inject faults via the helper scripts below."
+    HEADLESS_MODE="true"
+fi
+
+# Set up X11 forwarding only when a GUI will actually be shown
+if [[ "$HEADLESS_MODE" != "true" ]]; then
+    echo "Setting up X11 forwarding..."
+    if xhost +local:docker 2>/dev/null; then
+        X11_FORWARDING="true"
+    else
+        echo "   Warning: xhost failed. GUI may not work."
+        echo "   Install with: sudo apt install x11-xserver-utils"
+    fi
+fi
+
 # Export HEADLESS mode for docker-compose
 export HEADLESS=$HEADLESS_MODE
 echo "Gazebo mode: $([ "$HEADLESS_MODE" = "true" ] && echo "headless (no GUI)" || echo "GUI enabled")"