Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation — Docker (Recommended)

Docker provides a reproducible SRB environment with Isaac Sim 6.1.0 and Isaac Lab 3.0.0.

1. Clone the Repository

Clone SRB with its submodules:

git clone --recurse-submodules https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench

Without submodules, clone normally and initialize asset repos from a Hugging Face mirror:

git clone https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench
./assets/update.bash --source hf --repo-id <owner>/<repo>
./assets/update.bash --source hf --repo-id <owner>/<graphics-repo> --path docs/src/_graphics

2. Install Docker Engine & NVIDIA Container Toolkit

  1. Official instructions: Install Docker Engine
  2. Official instructions: Linux post-installation steps for Docker Engine
  3. Official instructions: Installing the NVIDIA Container Toolkit

Interactive use needs a working NVIDIA driver (nvidia-smi). GUI forwarding also needs xauth (sudo apt-get install -y xauth), an X11 session, and DISPLAY set.

Install Docker Engine and NVIDIA Container Toolkit using the official instructions or the pinned script:

./.docker/host/install_docker.bash

The helper supports Ubuntu 22.04/24.04 on amd64/arm64. It verifies the Docker repository key fingerprint (and the NVIDIA one when installing the toolkit), then installs Docker Engine/CLI 29.8.0, containerd.io 2.3.6, Buildx 0.37.1, Compose 5.6.0, rootless extras 29.8.0, and (when nvidia-smi detects a working GPU) NVIDIA Container Toolkit 1.20.0. It refuses unavailable package versions. Override pins with SRB_DOCKER_CE_VERSION, SRB_DOCKER_CLI_VERSION, SRB_DOCKER_CONTAINERD_VERSION, SRB_DOCKER_BUILDX_VERSION, SRB_DOCKER_COMPOSE_VERSION, SRB_DOCKER_ROOTLESS_EXTRAS_VERSION, or SRB_NVIDIA_TOOLKIT_VERSION; set SRB_INSTALL_NVIDIA_TOOLKIT=false to skip the toolkit. Non-interactive calls change Docker group membership only with SRB_ADD_DOCKER_GROUP=true.

If the installer adds your user to the docker group, start a new login session before relying on passwordless docker commands.

3. Run

Build the local image, then run it with the script:

SRB_IMAGE_NAME=space_robotics_bench ./.docker/build.bash 6.1.0
SRB_DOCKER_IMAGE='space_robotics_bench:6.1.0' ./.docker/run.bash

The runner resolves a local tag to its immutable image ID and never falls back to a remote tag. Default safe profile starts an interactive container with isolated networking and IPC, dropped capabilities, and no host devices or mounts. Use it for commands that do not need Isaac Sim host integration:

DOCKER_TTY=false ./.docker/run.bash srb --help

For a reviewed remote release, supply its complete registry digest; mutable tags are rejected:

SRB_DOCKER_IMAGE='<registry>/<image>@sha256:<64-hex-digest>' ./.docker/run.bash srb --help

Released images require a complete digest. Local tags resolve to image IDs only when present; missing local tags and remote mutable tags fail. join.bash selects source images with SRB_IMAGE_NAME and joins by container name; set SRB_CONTAINER_NAME consistently.

Isaac Sim needs the GPU. ROS 2 discovery and livestreaming also need host networking. Select the simulator profile:

SRB_DOCKER_PROFILE=simulator ./.docker/run.bash

The unprivileged simulator profile uses no-new-privileges, NVIDIA runtime, /dev/dri, host networking and IPC, writable simulator caches, GUI forwarding, history, and a writable /root/ws source mount by default. It has no --privileged or blanket /dev mount. Disable host networking or IPC independently:

# Bridge networking (no ROS 2 multicast discovery with host nodes)
SRB_DOCKER_PROFILE=simulator WITH_HOST_NETWORK=false ./.docker/run.bash

# Private IPC namespace with an explicit /dev/shm size (default 8g)
SRB_DOCKER_PROFILE=simulator WITH_HOST_IPC=false SRB_DOCKER_SHM_SIZE=16g ./.docker/run.bash

The trusted simulator profile enables --privileged and mounts all of /dev for hardware passthrough (cameras, serial adapters, joysticks); it prints a security warning. Use only with a locally trusted image or authenticated digest:

SRB_DOCKER_PROFILE=trusted-simulator ./.docker/run.bash

Useful variants:

# Headless simulator session
SRB_DOCKER_PROFILE=simulator WITH_GUI=false ./.docker/run.bash

# Kit-less CPU / non-GUI development path; this is not Isaac/GPU evidence
SRB_DOCKER_PROFILE=simulator WITH_GPU=false WITH_GUI=false ./.docker/run.bash

# Simulator without writable source or shell history
SRB_DOCKER_PROFILE=simulator WITH_DEV_VOLUME=false WITH_HISTORY=false ./.docker/run.bash

# Diagnostic override only; it does not prove that a usable GPU exists
SRB_DOCKER_PROFILE=simulator WITH_GPU_FORCE_NVIDIA=true ./.docker/run.bash

# Non-interactive command execution
DOCKER_TTY=false ./.docker/run.bash bash -lc "srb --help"

Pass container variables with -e. For secrets, prefer bare -e NAME: run.bash reads the exported caller value (not an internal script variable) and sends all -e values through a private temporary env-file, keeping values out of the Docker command line and ps. Empty names, whitespace or leading # in names, non-identifier bare names, and newline values exit 2; errors disclose only entry position and length. Docker sets these values at run time, so the image entrypoint still appends its own PYTHONPATH, LD_LIBRARY_PATH, PATH, and ROS entries. Override those variables inside the command instead.

To attach from another terminal while the container is still running:

./.docker/join.bash

Both scripts accept a trailing command:

SRB_DOCKER_PROFILE=simulator ./.docker/run.bash bash
./.docker/join.bash 0 fish

4. Verify Installation

If verification fails, see Troubleshooting.

Isaac Sim

Check GPU visibility:

nvidia-smi

Launch Isaac Sim:

"$HOME/isaac-sim/isaac-sim.sh"

The first launch can take a while while Isaac Sim compiles shaders and prepares the environment.

Space Robotics Bench

Check the srb command:

srb --help
srb cache update

After changing simulator pins, rebuild the image because an existing local tag may retain older dependencies. See Clean Cache before reusing caches across simulator versions.

Optional NVIDIA NGC Isaac Sim 6.1 lane

The official NGC image is an Isaac Sim compatibility probe, not an SRB image. Use an architecture-specific immutable digest, NVIDIA’s ACCEPT_EULA=Y, UID 1234:1234, /isaac-sim, and writable cache mounts; WebRTC requires --network=host. This probe does not certify SRB tasks, ROS, Rust, or source-build behavior.

The lane requires an RTX-class GPU and preflights hardware ray tracing; set SRB_REQUIRE_RTX=true to require it. GUI runs merge X credentials into ${TMPDIR:-/tmp}/srb-xauth-<project>-<user>/Xauthority, in a directory you own.

GUI Forwarding

If you expect GUI access, also verify:

echo "$DISPLAY"
test -n "$XAUTHORITY" && ls -l "$XAUTHORITY"

… continue with Basic Usage

Extras

Build a New Docker Image

If you want to build a custom Docker image, you can use the provided script:

./.docker/build.bash

The Dockerfile exports committed uv.lock with --frozen --all-extras --group image-runtime --group vcs-sources, then installs the project with --no-deps.

By default the build falls back to host networking when bridge DNS fails. Opt out with SRB_BUILD_NETWORK=default ./.docker/build.bash, or set "dns" in /etc/docker/daemon.json.

Join a Running Container

Join a running container from another terminal with the script:

./.docker/join.bash

With multiple containers, the script lists them and takes the index first. Set SRB_CONTAINER_NAME to match run.bash; it lists only <name> and <name><digits>, excluding NGC probes. For non-interactive callers such as CI, set DOCKER_TTY=false; otherwise docker exec --tty fails with the input device is not a TTY:

DOCKER_TTY=false ./.docker/join.bash 0 bash -lc "srb --help"

Development

Simulator, trusted simulator, and development profiles mount the repository workspace, so edits persist on the host. Safe does not mount the checkout.

Open the project as a Dev Container for development.

For development variables or extra bind mounts, use ./.docker/dev.bash; it wraps ./.docker/run.bash with the unprivileged simulator profile. SRB_DOCKER_PROFILE=trusted-simulator opts into --privileged and /dev, with a warning before launch. The wrapper defaults to LOG_LEVEL=info; set LOG_LEVEL=debug ./.docker/dev.bash ... for verbose Isaac and SimForge startup logs.

The wrapper persists Rust caches across containers. Host Cargo caches default to ~/.cache/space_robotics_bench/docker; set SRB_DOCKER_CACHE_DIR=/path/to/cache to change that root or SRB_CARGO_TARGET_DIR=/path/in/container to change the target path (default /root/.cache/srb/cargo-target). Do not use /root/.cargo/target as the target path.