Cross platform docker launch system and fix for GUI display issues on macOS with XQuartz for example 5 (#186)

- Fix macOS XQuartz display issues with dynamic DOCKER_DISPLAY variable
- Add platform-specific setup instructions for macOS, Linux, Windows
- Remove hard-coded IP addresses and display numbers
- Add comprehensive troubleshooting for common X11 connection errors
- Resolves Docker GUI display issues on macOS and improves cross-platform compatibility.

---------

Co-authored-by: Stefano Dalla Gasperina <stefano.dallagasperina@austin.utexas.edu>

Author: itsbharatj

examples/5_docker_turtlesim/README.md

@@ -1,21 +1,33 @@
 # Example - TurtleSim in Docker
-For users who want to test the MCP server without needing to install ROS, this is an example that provides a dockerized ROS2  container preinstalled with the simplest possible 'robot' in the ROS ecosystem - TurtleSim. 
+
+For users who want to test the MCP server without needing to install ROS, this is an example that provides a dockerized ROS2 container preinstalled with the simplest possible 'robot' in the ROS ecosystem - TurtleSim.
 
 Turtlesim is a lightweight simulator for learning ROS / ROS 2. It illustrates what ROS does at the most basic level to give you an idea of what you will do with a real robot or a robot simulation later on.
 
 ## Prerequisites
 
-✅ **Note:** This tutorial is designed to be run on linux and has been tested with Ubuntu as well as [Ubuntu running on WSL](https://apps.microsoft.com/detail/9pn20msr04dw?hl=en-US&gl=US). Being a dockerized container, it is likely to work on other OS versions as well with the correct X11 forwarding settings. 
+✅ **Cross-Platform Support:** This tutorial works on Linux, macOS, and Windows with proper X11/display forwarding setup. Each platform has specific requirements detailed below.
 
 Before starting this tutorial, make sure you have the following installed:
 
+### All Platforms
 - **Docker**: [Install Docker](https://docs.docker.com/get-docker/)
 - **Docker Compose**: Usually comes with Docker Desktop, or install separately
-- **X Server** (for Windows): Install [X410](https://x410.dev/) or another X Server from Microsoft Store
-- **X11 forwarding** (for Linux): `sudo apt-get install x11-apps`
-- **XQuartz** (for macOS): Install from [XQuartz website](https://www.xquartz.org/)
 
-**Note:** If your OS is Windows, take a look at the following:
+### Platform-Specific Requirements
+
+#### macOS
+- **XQuartz**: Install from [XQuartz website](https://www.xquartz.org/)
+- **Important**: XQuartz setup can be complex - see [macOS Setup](#macos-setup) section below for detailed instructions
+
+#### Linux
+- **X11 forwarding**: `sudo apt-get install x11-apps`
+- Usually works out of the box with minimal setup
+
+#### Windows
+- **X Server**: Install [X410](https://x410.dev/), [VcXsrv](https://sourceforge.net/projects/vcxsrv/), or another X Server from Microsoft Store
+- **WSL recommended**: Works best with Windows Subsystem for Linux
+
 <details>
 <summary><strong>PowerShell and WSL (Windows)</strong></summary>
 
@@ -36,23 +48,38 @@ cd examples/5_docker_turtlesim
 docker compose build --no-cache turtlesim
 ```
 
-### 2. Start the Container
+### 2. Launch Turtlesim
+
+#### Automatic Setup (Recommended)
 
-Launch the turtlesim container
+The easiest way to launch turtlesim with proper X11 setup:
 
 ```bash
-docker compose up
+./launch.sh
 ```
 
-If your OS is Windows and you want to launch docker in PowerShell, you first need to set the DISPLAY:
+This script automatically detects your OS and handles all platform-specific X11 configuration. It will:
+- **macOS**: Start XQuartz, detect display, configure IP-based forwarding
+- **Linux**: Set up X11 permissions with `xhost +local:docker`
+- **Windows**: Configure X server connection via `host.docker.internal`
+
+#### Manual Setup (Advanced)
+
+If you prefer manual control or the automatic script doesn't work:
+
+**macOS:**
 ```bash
-$env:DISPLAY="host.docker.internal:0.0"
+./docker/scripts/launch_macos.sh
 ```
 
-If your OS is Ubuntu/WSL and the docker doesn't run successfully, consider:
+**Linux (or Windows WSL):**
+```bash
+./docker/scripts/launch_linux.sh
+```
 
+**Windows:**
 ```bash
-dos2unix docker/scripts/launch_turtlesim.sh
+./docker/scripts/launch_windows.sh
 ```
 
 The container will automatically start both turtlesim and rosbridge websocket server. You should see:
@@ -69,16 +96,16 @@ Launch the container in the background:
 ```bash
 docker compose up -d
 ```
-And attach to the container
 
+And attach to the container:
 ```bash
 docker exec -it ros2-turtlesim bash
 ```
 
 Once inside the container, you can manually launch turtle teleop to control the turtle:
 
 ```bash
-source /opt/ros/humble/setup.bash
+source /opt/ros/${ROS_DISTRO}$/setup.bash
 ros2 run turtlesim turtle_teleop_key
 ```
 
@@ -87,45 +114,145 @@ This will allow you to use arrow keys or WASD to manually move the turtle around
 ## Integration with MCP Server
 
 Once turtlesim and rosbridge are running, you can connect the MCP server to control the turtle programmatically.
-Follow the [installation guide](../../docs/installation.md) for full setup instructions if you haven't already set up the MCP server. 
+Follow the [installation guide](../../docs/installation.md) for full setup instructions if you haven't already set up the MCP server.
 
-Since it is running on the same machine, you can tell the LLM to connect to the robot on localhost. 
+Since it is running on the same machine, you can tell the LLM to connect to the robot on localhost.
 
+## Platform-Specific Setup
 
-## Troubleshooting
+<details>
+<summary><strong>macOS Setup</strong></summary>
 
-### Display Issues (Linux)
+macOS requires special X11 forwarding setup. Follow these steps carefully:
 
-If you encounter display issues on Linux, run:
+### Step 1: Install XQuartz
+Download and install from [XQuartz website](https://www.xquartz.org/)
 
+### Step 2: Configure XQuartz
+1. **Start XQuartz**: `open -a XQuartz`
+2. **Wait for it to fully load** (you'll see an xterm window)
+
+### Step 3: Detect Your Setup
 ```bash
-xhost +local:docker
+# Check if XQuartz is running and which display it's using
+ps aux | grep -i xquartz
+
+# You should see something like:
+# /opt/X11/bin/Xquartz :1 -listen tcp ...
+# The `:1` or `:0` is your display number
+```
+
+### Step 4: Get Your Machine IP
+```bash
+# Get your machine's IP address
+ifconfig en0 | grep inet | awk '$1=="inet" {print $2}'
+# Example output: 10.1.56.72
+```
+
+### Step 5: Set Up Environment
+```bash
+# Set DISPLAY for your Mac (use the display number from Step 3)
+export DISPLAY=:1  # or :0 depending on what you found
+
+# Allow X11 connections
+xhost +
+
+# Set DISPLAY for Docker (use your IP from Step 4 + display number)
+export DOCKER_DISPLAY=<YOUR_IP>  # Replace with your actual IP
 ```
+</details>
+
+## Troubleshooting
 
-### Display Issues (macOS)
+### macOS Display Issues
 
-For macOS users, make sure XQuartz is running and configured:
+<details>
+<summary><strong>Problem: <code>qt.qpa.xcb: could not connect to display</code></strong></summary>
+
+**Solutions**:
+
+1. **Check XQuartz is running**:
+   ```bash
+   ps aux | grep X11
+   ```
+
+2. **Verify display number**:
+   ```bash
+   # Look for :0 or :1 in the Xquartz process
+   ps aux | grep Xquartz | grep -o ":[0-9]"
+   ```
+
+3. **Check your IP address**:
+   ```bash
+   ifconfig en0 | grep inet
+   ```
+
+4. **Set correct DOCKER_DISPLAY**:
+   ```bash
+   export DOCKER_DISPLAY="YOUR_IP:DISPLAY_NUMBER"
+   # Example: export DOCKER_DISPLAY="10.1.56.72:1"
+   ```
+
+5. **Allow X11 connections**:
+   ```bash
+   export DISPLAY=:1  # Use your display number
+   xhost +
+   ```
+</details>
+
+<details>
+<summary><strong>Problem: <code>xhost: unable to open display ":0"</code></strong></summary>
+
+**Solution**: XQuartz might be using `:1` instead of `:0`:
 
 ```bash
-# Start XQuartz
-open -a XQuartz
+export DISPLAY=:1
+xhost +
+```
+</details>
 
-# Allow connections from localhost
-xhost +localhost
+### Linux Display Issues
+
+<details>
+<summary><strong>Display issues on Linux</strong></summary>
+
+If you encounter display issues on Linux, run:
+
+```bash
+xhost +local:docker
 ```
+</details>
+
+### Windows Display Issues
+
+<details>
+<summary><strong>Display issues on Windows</strong></summary>
 
-### Display Issues (Windows/PowerShell)
 For Windows users, make sure you install an X Server (X410) and set the DISPLAY:
 
 ```bash
-$env:DISPLAY="host.docker.internal:0.0"
+$env:DOCKER_DISPLAY="host.docker.internal:0.0"
 ```
+</details>
+
+### General Issues
+
+<details>
+<summary><strong>Problem: Container starts but no window appears</strong></summary>
 
-### Container Networking
+**Solutions**:
+1. Check if the window is hidden behind other windows
+2. Look in Mission Control (macOS) or Alt+Tab (Windows/Linux)
+3. Verify your DOCKER_DISPLAY is set correctly for your platform
+</details>
 
-If you need to access the container from outside, the container uses host networking mode, so ROS2 topics should be accessible on localhost.
+<details>
+<summary><strong>Problem: <code>libGL error: No matching fbConfigs or visuals found</code></strong></summary>
 
-### Manual Launch (Alternative)
+**Solution**: This is just a warning and doesn't prevent the GUI from working. The turtlesim window should still appear.
+</details>
+
+## Manual Launch (Alternative)
 
 If the automatic launch isn't working or you prefer to launch turtlesim manually, you can run these commands inside the container:
 
@@ -134,7 +261,7 @@ If the automatic launch isn't working or you prefer to launch turtlesim manually
 docker exec -it ros2-turtlesim bash
 
 # Source ROS2 environment
-source /opt/ros/humble/setup.bash
+source /opt/ros/${ROS_DISTRO}$/setup.bash
 
 # Start turtlesim in one terminal
 ros2 run turtlesim turtlesim_node
@@ -143,11 +270,11 @@ ros2 run turtlesim turtlesim_node
 ros2 run turtlesim turtle_teleop_key
 ```
 
-### Testing Turtlesim
+## Testing Turtlesim
 
 If you need to verify that turtlesim is working correctly:
 
-#### ROS2 Topic Inspection
+### ROS2 Topic Inspection
 
 In a separate terminal, you can inspect the ROS2 topics:
 
@@ -156,7 +283,7 @@ In a separate terminal, you can inspect the ROS2 topics:
 docker exec -it ros2-turtlesim bash
 
 # Source ROS2 environment
-source /opt/ros/humble/setup.bash
+source /opt/ros/${ROS_DISTRO}$/setup.bash
 
 # List all topics
 ros2 topic list
@@ -168,7 +295,7 @@ ros2 topic echo /turtle1/pose
 ros2 topic echo /turtle1/cmd_vel
 ```
 
-#### ROS Bridge WebSocket Server
+### ROS Bridge WebSocket Server
 
 The rosbridge websocket server is automatically started and available at `ws://localhost:9090`. You can test the connection using a WebSocket client or the MCP server.
 
@@ -196,10 +323,8 @@ docker rmi ros-mcp-server_turtlesim
 
 Now that you have turtlesim running, you can:
 
-
 1. **Try more complex commands** like drawing shapes or following paths
 2. **Install ROS Locally** to add more nodes and services
 3. **Explore other examples in this repository**
 
-
-This example provides a foundation for understanding how the MCP server can interact with ROS2 systems, from simple simulators like turtlesim to complex robotic platforms. 
+This example provides a foundation for understanding how the MCP server can interact with ROS2 systems, from simple simulators like turtlesim to complex robotic platforms. 

examples/5_docker_turtlesim/docker-compose.yml

@@ -7,10 +7,14 @@ services:
     environment:
       - DISPLAY=${DISPLAY}
       - ROS_DISTRO=humble
+      - QT_X11_NO_MITSHM=1
     volumes:
+      # Mount launch file into the container
+      - ./launch_turtlesim.launch.py:/ros2_ws/launch/launch_turtlesim.launch.py:ro
+      # Linux X11 socket (only works on Linux)
       - /tmp/.X11-unix:/tmp/.X11-unix:rw
-      - ./docker/scripts:/ros2_ws/scripts:ro
-    network_mode: host
+    ports:
+      - "9090:9090"
     stdin_open: true
     tty: true
-    command: bash -c "/ros2_ws/scripts/launch_turtlesim.sh"
+    command: ["ros2", "launch", "/ros2_ws/launch/launch_turtlesim.launch.py"]