Docker & Devcontainers
Run the simulation inside a Docker container.
Everything runs inside a Docker container with all dependencies pinned and pre-built. It's slower to start than native (pixi) on most systems (not Linux, Docker there works at close-to-native speeds) but works on any OS, including Chrono, without a local ROS/Gazebo install. This project uses devcontainers, built with the VS Code extension or the CLI.
1. Build the devcontainer
Before the container starts, initializeCommand runs .devcontainer/host-env.sh, which detects your OS and GPU and writes docker/.env. These are all possible options:
| Host | Display path |
|---|---|
| Linux Wayland/X11 & WSL2/WSLg | Host socket, passed straight through |
| macOS + XQuartz | Forwarded over TCP via host.docker.internal & rendered with VirtualGL |
| Vanilla Windows | Forwarded over TCP to VcXsrv & rendered with VirtualGL |
| Linux + NVIDIA GPU | Uses the container toolkit and NVIDIA Docker runtime for faster rendering |
Open the repo in VS Code and accept the Reopen in Container prompt, or run Dev
Containers: Reopen in Container from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
Requires the Dev Containers
extension.
Configuration
Ports and flags & other configuration is in docker/.env.defaults. To change any, add it to
docker/.env.local.
2. Check if display works
Gazebo and RViz need a display. On container start, .devcontainer/x_server.sh picks the best
path for your host and prints which one it picked. Check the terminal you launched the
container from.
Wayland or X11 is forwarded straight through - no VNC needed. The log prints one of:
[X11] Using Wayland socket at /run/host-runtime/wayland-1
[X11] Using host X11 display at :0WSL2 uses the same path automatically via WSLg's built-in compositor.
Verify it works
- X11 (Gazebo/RViz): run
xeyesinside the container - a pair of animated eyes should appear. - Vulkan (Chrono): run
vkcubeinside the container - a spinning textured cube should render.
On macOS/Windows, xeyes only proves the X11 connection, not GL - check that separately:
$ vglrun /opt/VirtualGL/bin/glxspheres64A window of spinning spheres should appear, and the terminal should report a frame rate with
OpenGL Renderer: llvmpipe. vglrun: command not found means rebuild the container; "can't open
the 3D X server" means run bash .devcontainer/x_server.sh.
Running GUI apps by hand
sim gazebo prefixes vglrun for you automatically. Anything else you launch yourself that
uses OpenGL needs it too - vglrun rviz2, vglrun gz sim, etc. Plain X11 tools like xeyes
don't need it. This only applies on macOS/Windows; run normally on Linux/WSLg.
3. Launch the sim
Once the display works, head to Running Gazebo to launch your first sim.
NVIDIA Acceleration
Non-Ubuntu/Debian hosts
See the official install guide for other distros.
If you have a Linux system with a NVIDIA GPU, you can use a special Docker runtime (nvidia-container-toolkit) to give the container hardware access to it - this speeds up both GL rendering (Gazebo/RViz) and Vulkan (Chrono) in every display mode, not just VNC. host-env.sh detects it automatically and enables it for you, but the runtime has to be installed and registered with Docker first. On a Debian-based distro, run this on your host:
$ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
| sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
$ distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
$ curl -fsSL https://nvidia.github.io/libnvidia-container/libnvidia-container.list \
| sed 's|^deb |deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] |' \
| sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list > /dev/null
$ sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
$ sudo nvidia-ctk runtime configure --runtime=docker
$ sudo systemctl restart dockerVerify Docker can see the GPU:
$ docker run --rm --runtime=nvidia --gpus all nvidia/cuda:12.0-base-ubuntu22.04 nvidia-smi