{"id":18517443,"url":"https://github.com/turlucode/ros-docker-gui","last_synced_at":"2025-04-08T09:06:04.677Z","repository":{"id":25978326,"uuid":"107019849","full_name":"turlucode/ros-docker-gui","owner":"turlucode","description":"ROS Docker Containers with X11 (GUI) support [Linux]","archived":false,"fork":false,"pushed_at":"2025-03-21T14:19:18.000Z","size":191,"stargazers_count":212,"open_issues_count":2,"forks_count":54,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-01T08:29:41.742Z","etag":null,"topics":["cuda","docker","gui","nvidia","ros","ros2"],"latest_commit_sha":null,"homepage":"http://turlucode.com/ros-docker-container-gui-support/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turlucode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-15T14:32:04.000Z","updated_at":"2025-04-01T08:16:03.000Z","dependencies_parsed_at":"2024-01-15T13:44:05.168Z","dependency_job_id":"9101ccb6-9ec5-4d9e-9eca-1e3944c7b58c","html_url":"https://github.com/turlucode/ros-docker-gui","commit_stats":{"total_commits":126,"total_committers":5,"mean_commits":25.2,"dds":0.09523809523809523,"last_synced_commit":"b10634f4b965570e1d5f30ded2deec67094bb9c5"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turlucode%2Fros-docker-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turlucode%2Fros-docker-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turlucode%2Fros-docker-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turlucode%2Fros-docker-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turlucode","download_url":"https://codeload.github.com/turlucode/ros-docker-gui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809963,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuda","docker","gui","nvidia","ros","ros2"],"created_at":"2024-11-06T17:03:30.841Z","updated_at":"2025-04-08T09:06:04.657Z","avatar_url":"https://github.com/turlucode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `turludock` - Robot Operating System (ROS) Docker Containers with X11 and Wayland support for Linux\n[![N|Solid](http://turlucode.com/wp-content/uploads/2017/10/turlucode_.png)](http://turlucode.com/)\n\n`turludock` aims to provide different versions of ROS as Docker containers, but with GUI \nsupport for both X11 and Wayland!\nThis means your local OS is no more bound to the version of ROS you are using! \nYou can use _any_ version of ROS with _any_ Linux distribution, thanks to the amazing \npower of Docker!\n\n# TL;DR\n## Install tool - Python \u003e= 3.9\n```\npip install turludock\n```\n\n## Build image\n```sh\n# Build ROS image from presets (turludock which presets)\nturludock build -e noetic_mesa\n# Build using a custom configuration\nturludock build -c custom.yaml --tag custom_tag\n\n# Check supported versions\nturludock which ros\nturludock which cuda ROS_CODENAME\n```\nAll commands have a `--help` support.\n\u003e [Example YAML config](https://github.com/turlucode/ros-docker-gui/blob/master/examples/noetic_nvidia_custom.yaml)\n\n## Run container\n[See \"Running the image (as current user)\"](#running-the-image-as-current-user) on how to run a container.\n\n# Getting Started\nThe idea is to have HW accelerated GUIs with Docker. Generally it has proven that this is \na challenging task. Graphics card companies like NVIDIA, already provide \nsolutions for their platform. Running X11 applications within a Docker container is proven for\nthe last years. However, Wayland support remains still a bit challenging, but at least for\nour ROS containers we can assume it is supported :cake:.\n\n## Install `turludock`\n```sh\npip install turludock\n```\n\n## Supported tool functionality\nThis tool has two main functionalities:\n  1. **Build** ROS images which result in ready-to-use containers.\n  2. **Generate** Dockerfile and required assets for *manually building* the Docker images with `docker build`.\n\nSome more details with:\n```sh\nturludock --help\n```\n\n## Supported GPU drivers\nCurrently this project supports all HW accelerated containers, assuming your GPU is supported by\neither [`mesa`](https://www.mesa3d.org/) or NVIDIA drivers.\n\u003e For older Ubuntu versions that need support for state-of-the-art GPUs like the Radeon RX 7 series,\nwe rely on the [`ppa:kisak/kisak-mesa`](https://launchpad.net/~kisak/+archive/ubuntu/turtle)\nrepository.\n\n### NVIDIA GPU\nBoth the NVIDIA drivers and the [nvidia-container-toolkit] are required to be installed and working.\n\nYou test this by making sure `nvidia-smi` works:\n```sh\ndocker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi\n```\n\n### Known Wayland limitations\n\nROS related GUI programs seem to working fine. Other programs like `meld` or `vscode` also seem to be working fine. There might be cases where some GUIs do not work as expected. Feel free to open a ticket so we can look into it.\n\nFor example, we know RViz is not ready for Wayland; hence we will need to use the `xcb` (X11) plugin instead of the one for Wayland and therefore we will use `QT_QPA_PLATFORM=xcb` for all QT applications. More info in section [\"RViz Wayland known issues\"](#rviz-wayland-known-issues).\n\n## Supported ROS Images\n\nThe idea is to try and support all currently ROS versions that are not End-of-Life (EOL).\nBelow you can check all ROS1 and ROS2 distributions and their EOL status:\n- [ROS 1 distributions](http://wiki.ros.org/Distributions)\n- [ROS 2 distributions](https://docs.ros.org/en/rolling/Releases.html)\n\n\u003e Even if ROS 1 Noetic becomes EOL we will try to support it for longer time since many people might\nstill be relying on it :sunglasses:\n\nTo check which versions are actually supported use:\n```sh\nturludock which ros\n```\nThis will output ROS versions with their codename.\n\n## Supported CUDA and cuDNN versions\n\nTo see the supported versions of CUDA/cuDDN for a specific ROS version use:\n```sh\nturludock which cuda ROS_CODENAME\n```\n`ROS_CODENAME` could be `noetic` for example.\n\n# Build desired Docker Image\n\n*Hint: For more details and supported arguments*\n```sh\nturludock build --help\n# Or\nturludock generate --help\n```\n\n## Tool is based on YAML configurations\nThis tool uses a specific `.yaml` configuration to generate Dockerfiles or build Docker images.\n\nYou can find a [typical configuration](https://github.com/turlucode/ros-docker-gui/blob/master/examples/noetic_nvidia_custom.yaml) in the examples folder.\n\n### Build or generate from presets\nThis tool already provides preconfigured `.yaml` files that can be used directly to generate\nDockerfiles or build Docker images. This is what we call a list of *presets*: you might like\nthem and use them; or hate them and create your own :wink:.\n\nFor a list of available presets run:\n```sh\nturludock which presets\n```\nThis will show the underlying ROS version, the GPU driver assumed, the CUDA/cuDNN version (if applicable) \nand some preinstalled packages that are part of the preset.\n\nTo build a Docker image from the presets use:\n```sh\nturludock build -e noetic_mesa\n```\nOr if you want to generate the Dockerfile and its required assets for manual build use:\n```sh\nturludock generate -e noetic_mesa FOLDER_PATH\n```\nThe `FOLDER_PATH` now contains all necessary files to run a custom `docker build` command.\nSo you can just invoke `docker build FOLDER_PATH` for example.\n\n### Build or generate from custom YAML configuration\nOK, so you don't like the existing presets and you would like to build a Docker image using\nyour own custom configuration... \n\nNo problemo, use:\n```sh\nturludock build -c custom.yaml --tag CUSTOM_TAG\n```\n\u003e How to create a custom yaml configuration? [Check the example.](https://github.com/turlucode/ros-docker-gui/blob/master/examples/noetic_nvidia_custom.yaml)\n\nOr if you want to generate the Dockerfile and its required assets for manual build use:\n```sh\nturludock generate -c custom.yaml FOLDER_PATH\n```\nThe `FOLDER_PATH` now contains all necessary files to run a custom `docker build` command.\n\n# Running the image (as current user)\n## Mesa\n\u003e :pineapple: **Important:** Make sure your YAML configuration uses: [`gpu_driver: mesa`](https://github.com/turlucode/ros-docker-gui/blob/master/examples/noetic_nvidia_custom.yaml#L15)\n\n### X11\nTo run the ROS Docker container with X11 support use:\n```sh\ndocker run --rm -it --privileged --net=host --ipc=host \\\n--device=/dev/dri:/dev/dri \\\n-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY \\\n-v $HOME/.Xauthority:/home/$(id -un)/.Xauthority -e XAUTHORITY=/home/$(id -un)/.Xauthority \\\n-e DOCKER_USER_NAME=$(id -un) \\\n-e DOCKER_USER_ID=$(id -u) \\\n-e DOCKER_USER_GROUP_NAME=$(id -gn) \\\n-e DOCKER_USER_GROUP_ID=$(id -g) \\\n-e ROS_IP=127.0.0.1 \\\nturlucode/ros-noetic:mesa-cmake-tmux-llvm-meld\n```\n\n_Important Remarks_: \n\n- The `DOCKER_USER_*` variables are used to run the container as the current user.\n- Please note that you need to pass the `Xauthority` to the correct user's home directory.\n- You may need to run `xhost si:localuser:$USER` or worst case `xhost local:root` if get errors like `Error: cannot open display`.\n- See also section [\"Other options\"](#other-options) for other options.\n\n### Wayland\n\u003e **NOTE:** Wayland support is still a bit experimental! See section [\"Known Wayland limitations\"](#known-wayland-limitations).\n\nROS GUI on Wayland is still problematic and that is why we are going to use [`xwayland`](https://wayland.freedesktop.org/xserver.html).\nMake sure you have installed `xhost`.\nMake also sure the user has the rights to draw to the display; more info in section [\"X11: Error: cannot open display\"](#x11-error-cannot-open-display).\n\nTo run the ROS Docker container with Wayland support use:\n\n```sh\ndocker run --rm -it --security-opt seccomp=unconfined \\\n-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY \\\n-e XDG_RUNTIME_DIR=/run/user/$(id -u) \\\n-e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \\\n-v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/user/$(id -u)/$WAYLAND_DISPLAY \\\n--device /dev/dri \\\n--group-add video \\\n-e QT_QPA_PLATFORM=xcb \\\n-e XDG_SESSION_TYPE=wayland \\\n-e GDK_BACKEND=wayland \\\n-e CLUTTER_BACKEND=wayland \\\n-e SDL_VIDEODRIVER=wayland \\\n-e DOCKER_USER_NAME=$(id -un) \\\n-e DOCKER_USER_ID=$(id -u) \\\n-e DOCKER_USER_GROUP_NAME=$(id -gn) \\\n-e DOCKER_USER_GROUP_ID=$(id -g) \\\n-e ROS_IP=127.0.0.1 \\\nturlucode/ros-noetic:mesa-cmake-tmux-llvm-meld dbus-launch terminator\n```\n\nOr for Ubuntu 24.04 and up, `dbus-launch terminator` is not needed, just use:\n\n```sh\ndocker run [...] turlucode/ros-jazzy:mesa-cmake-tmux-llvm-meld\n```\n\n_Important Remarks_: \n\n- The `DOCKER_USER_*` variables are used to run the container as the current user.\n- We need to start `terminator` with `dbus-launch` for Ubuntu versions less than 24.04, i.e. for versions \u003c `jazzy`.\n- The `QT_QPA_PLATFORM=xcb` is for now intentionally as discussed.\nFor this reason also the `qtwayland5` package is not installed in our Docker images.\n- See also section [\"Other options\"](#other-options) for other options.\n\n## NVIDIA GPU\n\u003e :pineapple: **Important:** Make sure your YAML configuration uses: [`gpu_driver: nvidia`](https://github.com/turlucode/ros-docker-gui/blob/master/examples/noetic_nvidia_custom.yaml#L15)\n\nFor machines that are using NVIDIA graphics cards we need to have the [nvidia-container-toolkit] installed.\n\n### X11\n\nTo run the ROS Docker container with X11 support use:\n````sh\ndocker run --rm -it --runtime=nvidia --gpus all --privileged --net=host --ipc=host \\\n-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY \\\n-v $HOME/.Xauthority:/home/$(id -un)/.Xauthority -e XAUTHORITY=/home/$(id -un)/.Xauthority \\\n-e DOCKER_USER_NAME=$(id -un) \\\n-e DOCKER_USER_ID=$(id -u) \\\n-e DOCKER_USER_GROUP_NAME=$(id -gn) \\\n-e DOCKER_USER_GROUP_ID=$(id -g) \\\n-e ROS_IP=127.0.0.1 \\\nturlucode/ros-noetic:nvidia-cmake-tmux-llvm-meld\n````\n\n_Important Remarks_: \n\n- The `DOCKER_USER_*` variables are used to run the container as the current user.\n- Please note that you need to pass the `Xauthority` to the correct user's home directory.\n- You may need to run `xhost si:localuser:$USER` or worst case `xhost local:root` if get errors like `Error: cannot open display`\n- Adapt `--gpus all` to your needs\n- See also section [\"Other options\"](#other-options) for other options.\n\n### Wayland\n\u003e **NOTE:** Wayland support is still a bit experimental! See section [\"Known Wayland limitations\"](#known-wayland-limitations).\n\nROS GUI on Wayland is still problematic and that is why we are going to use [`xwayland`](https://wayland.freedesktop.org/xserver.html).\nMake sure you have installed `xhost`.\nMake also sure the user has the rights to draw to the display; more info in section [\"X11: Error: cannot open display\"](#x11-error-cannot-open-display).\n\nTo run the ROS Docker container with X11 support use:\n````sh\ndocker run --rm -it --runtime=nvidia --gpus all --privileged --net=host --ipc=host \\\n-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY \\\n-e XDG_RUNTIME_DIR=/run/user/$(id -u) \\\n-e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \\\n-v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:/run/user/$(id -u)/$WAYLAND_DISPLAY \\\n-e QT_QPA_PLATFORM=xcb \\\n-e XDG_SESSION_TYPE=wayland \\\n-e GDK_BACKEND=wayland \\\n-e CLUTTER_BACKEND=wayland \\\n-e SDL_VIDEODRIVER=wayland \\\n-e DOCKER_USER_NAME=$(id -un) \\\n-e DOCKER_USER_ID=$(id -u) \\\n-e DOCKER_USER_GROUP_NAME=$(id -gn) \\\n-e DOCKER_USER_GROUP_ID=$(id -g) \\\n-e ROS_IP=127.0.0.1 \\\nturlucode/ros-noetic:nvidia-cmake-tmux-llvm-meld dbus-launch terminator\n````\n\nOr for Ubuntu 24.04 and up, `dbus-launch terminator` is not needed, just use:\n\n```sh\ndocker run [...] turlucode/ros-jazzy:nvidia-cmake-tmux-llvm-meld\n```\n\n- The `DOCKER_USER_*` variables are used to run the container as the current user.\n- We need to now start `terminator` with `dbus-launch`\n- The `QT_QPA_PLATFORM=xcb` is for now intentionally as discussed.\nFor this reason also the `qtwayland5` package is not installed in our Docker images.\n- Please note that you need to pass the `Xauthority` to the correct user's home directory.\n- You may need to run `xhost si:localuser:$USER` or worst case `xhost local:root` if get errors like `Error: cannot open display`\n- Adapt `--gpus all` to your needs\n- See also section [\"Other options\"](#other-options) for other options.\n\n## Other options\n### Mount your ssh-keys\nFor both root and custom user use:\n\n```sh\n-v $HOME/.ssh:/root/.ssh\n```\nFor the custom-user the container will make sure to copy them to the right location.\n\n### Mount your local catkin_ws\n\nTo mount your local `catkin_ws` you can just use the following Docker feature:\n```sh\n# for root user\n-v $HOME/\u003csome_path\u003e/catkin_ws:/root/catkin_ws\n# for local user\n-v $HOME/\u003csome_path\u003e/catkin_ws:/home/$(id -un)/catkin_ws\n```\n\n### Passing a camera device\nIf you have a virtual device node like `/dev/video0`, e.g. a compatible usb camera, you pass this to the Docker container like this:\n```sh\n--device /dev/video0\n```\n\n# References\n## Wayland in Docker references\n\n- [mviereck/x11docker](https://github.com/mviereck/x11docker/wiki/How-to-provide-Wayland-socket-to-docker-container)\n- [stackexchange: How can I run a graphical application in a container under Wayland?](https://unix.stackexchange.com/a/359244/189868)\n- [rso2/RViz:  Wayland Support #847 ](https://github.com/ros2/rviz/issues/847#issuecomment-1506502560)\n- [github ticket: wayland libGL error](https://github.com/pygame/pygame/issues/3405#issuecomment-1221266709)\n- [archlinux: Wayland](https://wiki.archlinux.org/title/wayland)\n\n## RViz Wayland known issues\n\n- https://github.com/ros-visualization/rviz/issues/1442#issuecomment-553946698\n- https://github.com/ros2/rviz/issues/672#issuecomment-2041508267\n- https://github.com/ros2/rviz/issues/847#issuecomment-1503892696\n\n## OpenGL NVIDIA\n\n- https://gitlab.com/nvidia/container-images/opengl/-/tree/ubuntu22.04?ref_type=heads\n\n# Troubleshooting\n## Container eating up too much memory\nIs even a simple command inside Docker eating up crazy a lot of memory? This happens especially in arch-linux.\nChances are you have a \"miss-configured\" `LimitNOFILE`. See [here](https://github.com/containerd/containerd/issues/3201#issue-431539379),\n[here](https://github.com/moby/moby/issues/44547#issuecomment-1334125338), [here](https://bugs.archlinux.org/task/77548) for the reported issue.\n```sh\n# This is what is configured\ncat /usr/lib/systemd/system/containerd.service | grep LimitNOFILE\n# This is what is actually being used\nsystemctl show containerd | grep LimitNOFILE\n```\nIf `containerd.service` uses `infinity` better bound it with systemd with a new `.conf` file:\n```sh\n# /etc/systemd/system/containerd.service.d/30-override.conf\n[Service]\nLimitNOFILE=1048576\n```\nIf the folder `docker.service.d` doesn't exist, create it.\nNow reload service with:\n```sh\nsudo systemctl restart containerd \u0026\u0026 sudo systemctl daemon-reload\n```\nAnd you are good to go! The container feels also \"snappier\" now.\n\n## X11: Error: cannot open display\nAssuming `xhost` is installed and running on your host, you may need to run `xhost si:localuser:$USER` or worst case `xhost local:root`.\n\n### Docker security risks\n\nAre you worried about the security risks when exposing your X-server to the\ncontainer? Normally you should be! :smiley:\n\nThere are some nice articles that explain what is going on and what might be some extra\nsteps you can do, in order to be less exposed.\n\n1. [Docker Security Risks: GUIs + Xorg](https://nicroland.wordpress.com/2016/02/27/docker-security-risks-guis-xorg/)\n2. [Running a Graphical Application from a Docker Container - Simply and Securely](https://blog.artis3nal.com/blog/container-gui-app-pgmodeler/)\n3. Feel free to google/gpt the matter yourself. :wink:\n\nMost importantly you can also review the [template files](turludock/assets/dockerfile_templates/) in order to be absolutely sure you like what is being installed in the images when using the `turludock` tool.\n\n## Vscode crashes\n\nTry adding `--shm-size=8G` to your docker command.\n\n# Issues and Contributing\n  - Please let us know by [filing a new \nissue](https://github.com/turlucode/ros-docker-gui/issues/new).\n  - You can contribute by [opening a pull \nrequest](https://github.com/turlucode/ros-docker-gui/compare).\n\n## Base images\n### NVIDIA\nThe images on this repository are based on the following work:\n\n  - [nvidia-opengl](https://gitlab.com/nvidia/samples/blob/master/opengl/ubuntu14.04/glxgears/Dockerfile)\n  - [nvidia-cuda](https://gitlab.com/nvidia/cuda) - Hierarchy is base-\u003eruntime-\u003edevel\n\n## For developers - a quick how to\n\nThis project uses [`poetry`](https://python-poetry.org/) for packaging and dependency management.\nAfter [installing poetry](https://python-poetry.org/docs/#installation) you can basically create a [python virtual environment ](https://docs.python.org/3/library/venv.html) for one of the supported python versions, \u003e=3.9, and inside that new environment just install the dependencies with\n```sh\npoetry install \n```\nAfter that, you are good to go!\n\u003e Hint: You can [install pynev](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) if you want to check multiple python versions.\n### Coding style enforcement\nCheck and enforce the coding style with static analysis:\n```sh\npoetry run isort turludock \u0026\u0026 poetry run black turludock \u0026\u0026 poetry run pflake8 turludock\n```\n\n   [nvidia-docker]: https://github.com/NVIDIA/nvidia-docker\n   [nvidia-container-toolkit]: \nhttps://github.com/NVIDIA/nvidia-container-toolkit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturlucode%2Fros-docker-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturlucode%2Fros-docker-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturlucode%2Fros-docker-gui/lists"}