ros2dev by Docker run 啟動參數說明 ( by ros2_humble_gz_rviz_gpu/20250704 )

 以下是這支 docker run 指令中各參數的詳細說明，以助你理解每個選項的用途和效果。

[bash]
# 允許本地 Docker 容器存取 X11 顯示
xhost +local:docker

docker run -it -d --name ros2dev \
  --restart=always --gpus all \
  --net=host \
  --privileged \
  --env DISPLAY=$DISPLAY \
  --env QT_X11_NO_MITSHM=1 \
  --volume /tmp/.X11-unix:/tmp/.X11-unix:rw \
  --volume $(pwd)/ros2_data:/home/ubuntu/data \
  --device /dev/ttyACM0:/dev/ttyACM0 \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  ros2_humble_gz_rviz_gpu/20250704 \
  bash -c "source /opt/ros/humble/setup.bash && bash"

===============================================================================

參數	說明
xhost +local:docker	允許本地使用者 docker（本地 UNIX domain）存取 X11 伺服器，以便容器內的 GUI（如 Gazebo、RViz）能顯示到本機螢幕。
docker run	啟動並執行一個新的容器。
-it	結合 -i（保持標準輸入開啟）與 -t（分配虛擬終端機），使你可以在容器中進行互動式操作。
-d	以「背景模式」（detached）執行容器，命令執行後立即回到主機終端。
--name ros2dev	為容器指定名稱 ros2dev，方便後續透過名稱管理（如 docker stop ros2dev、docker logs ros2dev）。
--restart=always	容器異常退出或 Docker 重啟後，自動重啟此容器，確保長期穩定運行。
--gpus all	將主機上所有 GPU 都分配給此容器，允許容器內做 GPU 加速運算（需 Docker 19.03+ 與 NVIDIA Container Toolkit）。
--net=host	使用 主機網路模式，容器與主機共用網路堆疊，無 NAT，延遲更低，適合 ROS2 DDS 多播與網路通訊。
--privileged	賦予容器幾乎等同於主機的「特權」權限，才能存取低階裝置、修改網路設定等（如使用 --device 時通常搭配）。
--env DISPLAY=$DISPLAY	將主機的 DISPLAY 環境變數傳入容器，告訴容器 GUI 應該輸出到哪個 X11 顯示伺服器。
--env QT_X11_NO_MITSHM=1	解決 Qt 應用（如 RViz）在 X11 上使用共享記憶體時可能的顯示錯誤。
--volume /tmp/.X11-unix:/tmp/.X11-unix:rw	將主機的 X11 socket（Unix domain）掛載到容器，使容器內程式能透過該 Socket 與 X 伺服器溝通，rw 表示可讀寫。
--volume $(pwd)/ros2_data:/home/ubuntu/data	將當前工作目錄下的 ros2_data 資料夾映射到容器內 /home/ubuntu/data，用於持久化地圖、日誌或其他資料。
--device /dev/ttyACM0:/dev/ttyACM0	將主機的 USB 裝置（例如 Arduino、micro:bit 之類的 Serial 裝置）映射進容器，供容器內驅動程式或節點存取。
--device /dev/ttyUSB0:/dev/ttyUSB0	類似上條，映射另一個 USB Serial 設備（如 IMU、LiDAR 透過 USB 連線）。
ros2_humble_gz_rviz_gpu/20250704	要執行的 Docker 映像名稱及 Tag（版本標記），通常會標示 ROS 版本、包含的軟體與建立日期。
bash -c "source /opt/ros/humble/setup.bash && bash"	容器啟動後執行的命令：先 source ROS 2 環境設定，然後開啟一個互動式 bash，讓你馬上能夠使用 ROS2 指令。

💡 小技巧

• 顯示 GUI：需先在主機執行 xhost +local:docker，並將 /tmp/.X11-unix 與 DISPLAY 傳入容器。

• 持久化資料：使用 --volume $(pwd)/ros2_data:/home/ubuntu/data，即使重建或刪除容器，資料仍保留在主機。

• 多設備：--device 可以多次指定，用於連接多種實體硬體（USB、串口、GPU）。

• 自動重啟：--restart=always 保證服務長期在線，適合開發板或長期測試。

• 網路模式：--net=host 避免 ROS2 DDS 的多播發不出的問題，但在跨主機部署時需注意安全性。

這樣的設定能讓你在容器內 完整模擬（Gazebo）、可視化（RViz）以及與實體硬體串接（IMU、Arduino、LiDAR）時，都擁有接近原生的體驗。

=================================================

以下是這份 docker‑compose.yml 主要欄位的功能與建議設定，幫你釐清每個參數的意義與用途：

[yaml]
version: "3.8"

services:
  ros2dev:
    build: .
    container_name: ros2_humble_gz_gpu

    # ---------- GPU 支援 ----------
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    runtime: nvidia

    # ---------- 環境變數 ----------
    environment:
      - NVIDIA_VISIBLE_DEVICES=all          # 容器可見所有 GPU
      - NVIDIA_DRIVER_CAPABILITIES=graphics,utility,video,compute
      - DISPLAY=${DISPLAY}                  # 傳遞主機 DISPLAY，啟用 GUI
      - QT_X11_NO_MITSHM=1                  # 解決 Qt X11 共享記憶體問題

    # ---------- Volume 掛載 ----------
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix:rw    # X11 Socket，用於顯示 Gazebo/RViz
      - ./src:/root/ros2_ws/src:rw          # 專案原始碼掛載到容器

    network_mode: host                       # 與主機共用網路堆疊
    privileged: true                         # 賦予容器特權模式，可存取所有裝置
    stdin_open: true                         # -i 保持 stdin
    tty: true                                # -t 分配虛擬終端

---

各參數說明

• version: "3.8"
  定義 Compose 檔案的語法版本，3.8 支援 deploy.resources 等新功能。

• services → ros2dev
  服務名稱，自訂為 ros2dev，後面所有設定都套用在這個容器上。

• build: .
  以當前目錄的 Dockerfile 來建置映像。

• container_name: ros2_humble_gz_gpu
  容器啟動後的名稱，方便用 docker ps、docker logs、docker exec 等指令操作。

---

GPU 支援

• deploy.resources.reservations.devices.capabilities: [gpu]
  宣告此服務需要 GPU，當你使用 Swarm 或支援 deploy 的環境時才會生效。

  ⚠️ 如果你用的是單機 Docker Compose（非 Swarm），這段通常不會生效，你可以直接在 CLI 加上 --gpus all。

• runtime: nvidia
  指定使用 NVIDIA Container Runtime，確保容器可以存取 GPU。

---

環境變數

• NVIDIA_VISIBLE_DEVICES=all
  讓容器看得到所有 GPU，或改為 0,1 只顯示指定卡號。

• NVIDIA_DRIVER_CAPABILITIES=graphics,utility,video,compute
  啟用 GPU 的圖形、計算等功能，必須包含 compute 才能跑 CUDA。

• DISPLAY=${DISPLAY}
  傳遞主機的 DISPLAY，告訴容器 GUI 畫面要輸出到哪個螢幕。

• QT_X11_NO_MITSHM=1
  解決 Qt 應用（如 RViz）在 X11 上的共享記憶體錯誤。

---

Volume 掛載

• /tmp/.X11-unix:/tmp/.X11-unix:rw
  掛載主機的 X11 Unix Socket，讓容器透過這個 Socket 與 X11 伺服器通訊，才能顯示 Gazebo、RViz。

• ./src:/root/ros2_ws/src:rw
  將當前目錄下的 src（你的 ROS2 原始碼）掛到容器的工作目錄，方便在本機修改程式後立即反映到容器內。

---

網路與權限

• network_mode: host
  容器與主機共用網路堆疊，DDS 多播等通訊可直接發送到本機網路。

• privileged: true
  賦予容器幾乎與主機相同的權限，可存取全部裝置，適合要操作串口、GPIO、USB 等硬體。

• stdin_open: true (-i)
  保持標準輸入開啟，使你可以 docker attach 或 docker exec -it 進行互動。

• tty: true (-t)
  為容器分配虛擬終端機，使輸出排版漂亮。

---

啟動方式建議

如果你的 Compose 版本不支援 deploy.resources，可改用：

bash
docker compose --profile=gpu up --build

或在 CLI 加上 GPU 參數：

bash
docker-compose up -d --build
# 然後手動執行：
docker run --gpus all ...

如此一來，既能在容器中使用 Gazebo、RViz，又能透過 USB、TTY 控制真實硬體，是開發與測試 ROS2 自走車的理想配置。