Docker 指南

Docker 指南#

小心

由于依赖于 Isaac Sim docker 镜像，通过运行此容器，您隐含地同意 NVIDIA Omniverse EULA 。如果您不同意该最终用户许可协议，请不要运行此容器。

设置说明#

备注

以下步骤取自NVIDIA Omniverse Isaac Sim文档中的 container installation 。它们被添加在这里是为了完整起见。

Docker 和 Docker Compose#

我们已经测试了 Docker Engine 版本26.0.0 和 Docker Compose 版本2.25.0。我们建议使用这些版本或更新版本。

安装 Docker，请按照 Docker website 上您操作系统的说明进行操作。
要安装 Docker Compose，请按照 docker compose 页面上您操作系统的说明进行操作。
按照 post-installation steps 页面上的后续步骤进行Docker的安装。这些步骤允许您在不使用 sudo 的情况下运行 Docker。
要构建和运行 GPU加速容器，您还需要安装 NVIDIA Container Toolkit 。请按照 Container Toolkit website 上的说明进行安装。

备注

由于对 snap 的限制，请确保Isaac Lab目录位于 /home 目录树下使用docker时。

获取 Isaac Sim 容器#

通过加入 NVIDIA Developer Program 凭据来获得对 Isaac Sim容器的访问权限。
生成您的 NGC API密钥以访问NVIDIA GPU Cloud (NGC)中的锁定容器镜像。
- 如果您尚未拥有NGC账户，则需要创建一个NGC账户才能执行此步骤。
- 还需要安装NGC CLI以从命令行执行操作。
- 一旦您生成了 API密钥并安装了NGC CLI，您需要从终端登录到NGC。
```
ngc config set
```
使用命令行从NGC中拉取Isaac Sim容器镜像。
```
docker login nvcr.io
```
- 对于用户名，输入 $oauthtoken ，如所示。这是用于与NGC进行身份验证的特殊用户名。
```
Username: $oauthtoken
Password: <Your NGC API Key>
```

目录组织#

Isaac Lab存储库的根目录包含名为 docker 的目录，其中包含运行Isaac Lab所需的各种文件和脚本。以下是其中的一部分摘要 :

Dockerfile.base: 定义了基础 Isaac Lab 镜像，通过将其依赖项叠加到 Isaac Sim Docker 镜像上。以其他名称结尾的 Dockerfile（即 Dockerfile.ros2 ）构建 image extension 。
docker-compose.yaml: 创建挂载以允许从运行容器的主机直接编辑 Isaac Lab 代码。它还创建了几个命名卷，例如 isaac-cache-kit ，用于存储 Isaac Sim 编译的频繁重用的资源，如着色器，并保留日志、数据和文档。
.env.base: 存储 base 构建过程和容器本身所需的环境变量。以其他内容结尾的 .env 文件（即 .env.ros2 ）为 image extension 定义这些变量。
container.py: 一个实用脚本，它与 utils 中的工具接口，配置和构建镜像，并运行和交互容器。

运行容器#

备注

Docker容器在构建时将所有文件从仓库复制到容器中的 /workspace/isaaclab 路径。这意味着在构建完成后，即在运行 ./container.py start 后，对容器中的文件所做的任何更改通常不会反映到仓库中。

为了使开发周期更快，我们将Isaac Lab存储库中的以下目录挂载到容器中，以便您可以从主机编辑其文件 :

IsaacLab/source: 这是包含 Isaac Lab 源代码的目录。
IsaacLab/docs: 这是包含 Isaac Lab 文档源代码的目录。这个目录会被覆盖，但 _build 子目录除外，后者存储了构建生成的工件。

脚本 container.py 与基本的 docker compose 命令相对应。每个命令都可以接受一个 image extension argument ，否则它们将默认为 base 镜像扩展。这些命令是：

这会构建镜像并以分离模式（即在后台）启动容器。
enter: 这会在现有的 Isaac Lab 容器中开始一个新的 bash 进程，并且可以退出而不会关闭容器。
config: 这会输出 compose.yaml，该文件是根据提供给 container.py start 的输入生成的。此命令对于调试 compose 配置非常有用。
copy: 这会将 logs 、 data_storage 和 docs/_build 文件从 isaac-lab-logs 、 isaac-lab-data 和 isaac-lab-docs 卷中分别复制到 docker/artifacts 目录。这些文件在 docker 容器实例之间保持不变，并在镜像扩展之间共享。
stop: 这会关闭容器并将其删除。

以下显示了如何在分离状态下启动容器并进入它 :

# Launch the container in detached mode
# We don't pass an image extension arg, so it defaults to 'base'
./docker/container.py start

# If we want to add .env or .yaml files to customize our compose config,
# we can simply specify them in the same manner as the compose cli
# ./docker/container.py start --file my-compose.yaml --env-file .env.my-vars

# Enter the container
# We pass 'base' explicitly, but if we hadn't it would default to 'base'
./docker/container.py enter base

要将文件从基础容器复制到主机，您可以使用以下命令：

# Copy the file /workspace/isaaclab/logs to the current directory
docker cp isaac-lab-base:/workspace/isaaclab/logs .

脚本 container.py 提供了一个封装此命令的方式，将 logs 、 data_storage 和 docs/_build 目录复制到 docker/artifacts 目录。这对于复制日志、数据和文档非常有用：

# stop the container
./docker/container.py stop

X11 转发#

容器支持 X11 转发，允许用户在容器中运行 GUI 应用程序，并在主机上显示它们。

第一次使用 ./docker/container.py start 启动容器时，脚本会提示用户是否激活 X11 转发。这将创建一个位于 docker/.container.cfg 的文件，以存储用户的选择以供将来使用。

如果你想更改选择，可以在 docker/.container.cfg 文件中将参数 X11_FORWARDING_ENABLED 设置为 ‘0’ 或 ‘1’，以分别禁用或启用 X11 转发。之后，你需要通过运行 ./docker/container.py start 来重新构建容器。重新构建过程确保更改应用到容器中。否则，更改将不会生效。

容器启动后，您可以进入容器并启用 X11 转发运行 GUI 应用程序。显示将被转发到主机机器。

Python 解释器#

容器使用Isaac Sim提供的Python解释器。此解释器位于 /isaac-sim/python.sh 。我们在容器内设置别名，以便更容易地运行Python解释器。您可以使用以下命令运行Python解释器 :

# Run the Python interpreter -> points to /isaac-sim/python.sh
python

理解挂载卷#

docker-compose.yaml 文件创建了几个命名卷，它们被挂载到容器。以下是这些卷的摘要 :

卷名	描述	容器路径
isaac-cache-kit	存储缓存的 Kit 资源	/isaac-sim/kit/cache
isaac-cache-ov	存储缓存的 OV 资源	/root/.cache/ov
isaac-cache-pip	存储缓存的 pip 资源	/root/.cache/pip
isaac-cache-gl	存储缓存的 GLCache 资源	/root/.cache/nvidia/GLCache
isaac-cache-compute	存储缓存的计算资源	/root/.nv/ComputeCache
isaac-logs	存储由 Omniverse 生成的日志	/root/.nvidia-omniverse/logs
isaac-carb-logs	存储由 carb 生成的日志	/isaac-sim/kit/logs/Kit/Isaac-Sim
isaac-data	存储由 Omniverse 生成的数据	/root/.local/share/ov/data
isaac-docs	存储由 Omniverse 生成的文档	/root/Documents
isaac-lab-docs	存储 Isaac Lab 的文档，当在容器内构建时	/workspace/isaaclab/docs/_build
isaac-lab-logs	存储由 Isaac Lab 工作流生成的日志，当它们在容器内运行时	/workspace/isaaclab/logs
isaac-lab-data	存储用户可能希望在容器运行之间保留的所有数据	/workspace/isaaclab/data_storage

要查看这些卷的内容，您可以使用以下命令：

# list all volumes
docker volume ls
# inspect a specific volume, e.g. isaac-cache-kit
docker volume inspect isaac-cache-kit

Isaac Lab 镜像扩展#

生成的镜像取决于传递给 container.py start 和 container.py stop 的参数。这些命令接受一个镜像扩展参数作为附加参数。如果没有传递参数，则该参数默认为 base 。目前，唯一有效的值是 (base, ros2 )。一次只能传递一个镜像扩展。生成的容器将被命名为 isaac-lab-${profile} ，其中 ${profile} 是镜像扩展名。

# start base by default
./docker/container.py start
# stop base explicitly
./docker/container.py stop base
# start ros2 container
./docker/container.py start ros2
# stop ros2 container
./docker/container.py stop ros2

传递的镜像扩展名参数将构建在 Dockerfile.${image_extension} 中定义的镜像，使用 docker-compose.yaml 中的对应 profile 和来自 .env.${image_extension} 的环境变量，以及 .env.base ，如果有的话。

ROS2 镜像扩展#

在 Dockerfile.ros2 中，容器通过 apt package 安装 ROS2 Humble，并在 .bashrc 中进行了源配置。具体版本由 .env.ros2 文件中的变量 ROS_APT_PACKAGE 指定，默认为 ros-base 。其他相关的 ROS2 变量也在 .env.ros2 文件中指定，包括定义 various middleware 选项的变量。

容器默认使用 FastRTPS，但也支持 CycloneDDS。这些中间件中的每一个都可以通过其对应的 .xml 文件在 docker/.ros 下进行 tuned。

已知问题#

WebRTC 流#

从 Isaac Sim 中流式传输 GUI 时，有几种流媒体客户端可供选择。尝试在容器中运行 Isaac Sim 时，使用 WebRTC 流客户端在 Google Chrome 和 Safari 上可能会出现已知问题。为了避免此问题，我们建议使用本机流式传输客户端或在支持 WebRTC 的 Mozilla Firefox 浏览器上运行。

从容器内可视化 Isaac GUI 的唯一支持方法是流式传输。 Omniverse 流式传输客户端可以从 Omniverse 应用中免费获取，并且易于使用。其他流式传输方法同样只需要一个网络浏览器。如果用户希望使用 X11 转发以使应用程序表现为本地 GUI 窗口，可以取消注释 docker-compose.yaml 中的相关部分。