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

itsbharatj · 2025-11-04T19:20:36Z

Overview

This PR addresses issue #101 and supersedes PR #153 for turtlesim Docker GUI testing.

Changes Made

1. Cross-Platform Launch System

Added launch.sh main script that automatically detects the host OS
Created platform-specific launch scripts:
- launch_macos.sh for macOS with XQuartz support
- launch_linux.sh for native Linux X11 environments
- launch_windows.sh for Windows using VcXsrv, X410 or other X servers
Improved error handling and user feedback throughout the launch process

2. macOS XQuartz Integration

Implemented automatic XQuartz startup detection and initialization
Fixed X11 authorization issues that caused first-run failures
Added proper display detection using hostname -I fallback for IP resolution
Removed hard-coded IP addresses and display numbers

3. Documentation Improvements

Updated README.md with platform-specific setup instructions
Added comprehensive troubleshooting section covering:
- XQuartz configuration requirements
- Common X11 connection errors and solutions
- Docker permissions and display issues
- Step-by-step debugging guide

4. Error Handling

Added validation for required commands (xhost, docker, etc)
Improved error messages with actionable troubleshooting steps
Added graceful fallbacks for authorization methods

Testing

Thoroughly tested on:

macOS with XQuartz
Verified container GUI display functionality
Tested cold-start scenarios (XQuartz not running)
Validated error messages and troubleshooting steps

Resolves

Works on #101
Supersedes #153

- 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.

…ty and X11 support

stex2005 · 2025-11-04T19:25:00Z

mcp_json.txt

This should be removed. It also contains your personal information.

Yes, I have removed it

stex2005 · 2025-11-04T19:25:54Z

examples/5_docker_turtlesim/README.md

+xhost +
+
+# Set DISPLAY for Docker (use your IP from Step 4 + display number)
+export DOCKER_DISPLAY="10.1.56.72:1"  # Replace with your actual IP


<YOUR_IP> instead of a random number

This has now been updated

stex2005 · 2025-11-04T19:27:24Z

examples/5_docker_turtlesim/README.md


 ```bash
-docker compose up
+./launch.sh


I am confused, the entire point of having docker compose up is that it doesn't need external configuration. I am not sure how I feel about having custom launch.sh floating around the repository, but I am no expert.

@rjohn-v?

I understand your concern @stex2005. However, the launch.sh script addresses host-side X11/GUI configuration, which is separate from the Docker container setup.

The problem:
On macOS (and some Linux systems), docker compose up alone isn't sufficient because:

DISPLAY environment variable - Needs to be dynamically determined (varies by machine/network)

XQuartz permissions - Requires xhost authorization before Docker can connect

XQuartz startup - Must be running and properly configured with "Allow connections from network clients"

IP-based display - macOS requires <IP>:<DISPLAY_PORT>

The script automates these host-side prerequisites before running docker compose up.

stex2005 · 2025-11-04T19:28:13Z

examples/5_docker_turtlesim/scripts/launch.sh

Not sure how I feel about encapsulating multiple .sh files instead of the cleaner docker compose up.
Asking for input from others.

stex2005 · 2025-11-04T19:29:00Z

examples/5_docker_turtlesim/docker-compose.yml

    stdin_open: true
    tty: true
-    command: bash -c "/ros2_ws/scripts/launch_turtlesim.sh"
+    command: ["/bin/bash", "/ros2_ws/scripts/launch_turtlesim.sh"]


This has actually been removed, there should be a proper ros2 launch file instead.

The scripts folder doesn't exist anymore, there is only a launch folder:

There is a template launch_rosbridge.launch.py, we can create inside 5_docker_turtlesim another simple launch file based on launch_rosbridge + the turtlesim node

Okay, let me make that change. Thanks!

stex2005 · 2025-11-04T19:30:54Z

.github/workflows/test-docker-turtlesim.yml

Can you briefly explain what this does? Does it have to be run at each push? This is just an example: I would trigger it the on workflow_dispatch ?

Sorry, I was using it for internal testing, I had removed it in a recent commit

stex2005 · 2025-11-04T19:35:49Z

@itsbharatj I think we could have kept the CI workflow in the example, but have it triggered only by on_dispatch, does it make sense?

itsbharatj · 2025-11-05T13:38:57Z

Hey @stex2005, based on your comments, I have pushed the respective changes:

Changed the path in docker-compose.yml from scripts to launch
From the launch_rosbridge.launch.py template, I have created the launch_turtlesim.launch.py which I have tested on my machine

The struggle is that I want to test the turtelsim ui being displayed using the websocket on multiple OS. I am not sure how can I test it using GitHub CI.

Also, please look at my reply for the using a singular launch.sh.

Let me know your thoughts,

Best
Bharat Jain

itsbharatj · 2025-11-06T23:33:05Z

Hey @stex2005, wanted to follow up and see if you’ve had a chance to go through the recent commits.

Thanks,
Bharat

itsbharatj · 2025-11-11T02:47:30Z

@stex2005, thank you for merging the PR.
Because the docker folder was removed, the paths in the run scripts also had to be changed.
I have fixed the following bug in #195.

itsbharatj and others added 10 commits October 7, 2025 21:47

Fixed the error in building uv venv

8b41691

Merge branch 'develop' into develop

071738c

Merge branch 'robotmcp:develop' into develop

8038651

feat: Enhance turtlesim launch scripts for cross-platform compatibili…

35b4d05

…ty and X11 support

Added CI test

679e2e0

Added CI test

d315bb5

launch scripts

237b360

Removed ci

d9d474a

Delete mcp_json.txt

1c2229f

stex2005 requested changes Nov 4, 2025

View reviewed changes

itsbharatj added 2 commits November 5, 2025 01:12

updated README

c147d59

*launch.py for turtlesim docker

5109cf1

itsbharatj requested a review from stex2005 November 5, 2025 13:33

itsbharatj changed the title ~~Fix Docker GUI display issues for turtlesim on macOS with XQuartz~~ Cross Platform Docker Launch for example 5 and fix for GUI display issues on macOS with XQuartz Nov 5, 2025

itsbharatj changed the title ~~Cross Platform Docker Launch for example 5 and fix for GUI display issues on macOS with XQuartz~~ Cross platform docker launch system and fix for GUI display issues on macOS with XQuartz for example 5 Nov 5, 2025

itsbharatj and others added 4 commits November 7, 2025 05:08

Merge branch 'develop' into develop

f051e3e

Merge branch 'develop' into develop

f2f88d6

Merge branch 'develop' into develop

b80a351

Reorganize docker turtlesim example scripts

d9db7b3

stex2005 merged commit e578f48 into robotmcp:develop Nov 10, 2025
1 check passed

itsbharatj mentioned this pull request Nov 11, 2025

Fixed the scripts path in example 5 #195

Merged

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

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

Uh oh!

Conversation

itsbharatj commented Nov 4, 2025

Overview

Changes Made

1. Cross-Platform Launch System

2. macOS XQuartz Integration

3. Documentation Improvements

4. Error Handling

Testing

Resolves

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itsbharatj Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stex2005 commented Nov 4, 2025

Uh oh!

itsbharatj commented Nov 5, 2025

Uh oh!

itsbharatj commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

itsbharatj commented Nov 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

itsbharatj Nov 4, 2025 •

edited

Loading

itsbharatj commented Nov 6, 2025 •

edited

Loading