Docker 指南

小心

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

设置说明

备注

以下步骤取自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 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 。

ROS2 镜像扩展的参数

###
# ROS2 specific settings
###
# Set the version of the ROS2 apt package to install (ros-base, desktop, desktop-full)
ROS2_APT_PACKAGE=ros-base
# Set ROS2 middleware implementation to use (e.g. rmw_fastrtps_cpp, rmw_cyclonedds_cpp)
RMW_IMPLEMENTATION=rmw_fastrtps_cpp
# Path to fastdds.xml file to use (only needed when using fastdds)
FASTRTPS_DEFAULT_PROFILES_FILE=${DOCKER_USER_HOME}/.ros/fastdds.xml
# Path to cyclonedds.xml file to use (only needed when using cyclonedds)
CYCLONEDDS_URI=${DOCKER_USER_HOME}/.ros/cyclonedds.xml

运行预构建的Isaac Lab容器

在 Isaac Lab 2.0 版本中，我们引入了一个最小化的预构建容器，容器内包含了一组非常基础的 Isaac Sim 和 Omniverse 依赖项，以及已经预构建好的 Isaac Lab 2.0。这个容器允许用户直接从 NGC 拉取容器，而不需要在本地构建 docker 镜像。Isaac Lab 2.0 的源代码将可以在这个容器内的 /workspace/IsaacLab 路径下找到。

这个容器仅设计用于运行 headless ，不允许进行 X11 转发或以 GUI 方式运行。请仅将此容器用于无头训练。对于其他使用场景，我们建议按照上述步骤构建您自己的 Isaac Lab docker 镜像。

要拉取最小的 Isaac Lab 容器，请运行:

docker pull nvcr.io/nvidia/isaac-lab:2.0.2

要运行带有交互式 bash 会话的 Isaac Lab 容器，请运行:

docker run --name isaac-lab --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --rm --network=host \
   -e "PRIVACY_CONSENT=Y" \
   -v ~/docker/isaac-sim/cache/kit:/isaac-sim/kit/cache:rw \
   -v ~/docker/isaac-sim/cache/ov:/root/.cache/ov:rw \
   -v ~/docker/isaac-sim/cache/pip:/root/.cache/pip:rw \
   -v ~/docker/isaac-sim/cache/glcache:/root/.cache/nvidia/GLCache:rw \
   -v ~/docker/isaac-sim/cache/computecache:/root/.nv/ComputeCache:rw \
   -v ~/docker/isaac-sim/logs:/root/.nvidia-omniverse/logs:rw \
   -v ~/docker/isaac-sim/data:/root/.local/share/ov/data:rw \
   -v ~/docker/isaac-sim/documents:/root/Documents:rw \
   nvcr.io/nvidia/isaac-lab:2.0.2

要在容器中运行示例，请运行:

./isaaclab.sh -p scripts/tutorials/00_sim/log_time.py --headless