Installation — Apptainer/Singularity

You can use SRB on HPC clusters or systems where Docker is not available by leveraging Apptainer. Apptainer is a containerization tool similar to Docker but designed for environments with stricter security policies or without Docker support.

Note: Building the Apptainer image (Step 2 below) still requires Docker on your local machine, since the .sif is converted from the SRB Docker image. Only the resulting .sif runs on the Docker-free target cluster — so build locally, then transfer.

Setup (Local)

1. Clone the Repository

First, clone the SRB repository with all submodules:

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

If you prefer not to use git submodules, you can clone normally and then 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

All remaining local-build commands in this guide assume your current working directory is the repository root.

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

Install Docker Engine and NVIDIA Container Toolkit either by following the official instructions above or using the provided convenience script:

./.docker/host/install_docker.bash

This local build path still depends on Docker because the Apptainer image is produced from the repository Docker image first.

3. Install Apptainer

Official instructions: Installing Apptainer

Install Apptainer by following the official instructions above. For instance, you can use these commands on Ubuntu:

sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt update
sudo apt install -y apptainer

4. Build the Apptainer Image

Now you can build the Apptainer image with the provided script:

./.docker/hpc/build.bash

The build script first runs ./.docker/build.bash, then converts the resulting Docker image into an Apptainer image at:

.docker/hpc/images/space_robotics_bench.sif

Deployment (HPC Cluster)

1. Transfer the Repository (with the Apptainer Image)

Transfer the local SRB repository to the HPC cluster using your preferred method (e.g., scp or rsync):

A. scp

scp -r /path/to/space_robotics_bench user@hpc-cluster:/path/to/space_robotics_bench

B. rsync

rsync -avr /path/to/space_robotics_bench user@hpc-cluster:/path/to/space_robotics_bench

2. SSH into the HPC Cluster

SSH into the HPC cluster:

ssh user@hpc-cluster

3. Run the Apptainer Image

Now you can run the Apptainer image with the provided script inside an interactive session (you might need make some adjustments based on your HPC environment):

# HPC interactive session
/path/to/space_robotics_bench/.docker/hpc/run.bash bash

Notes about run.bash:

• it expects to run on a node where the module command is available
• it loads tools/Singularity automatically
• it mounts the repository at /root/ws
• it persists Isaac Sim and SimForge caches under ${SCRATCH:-$HOME}/volumes/space_robotics_bench/
• WITH_GPU=true by default and adds --nv; set WITH_GPU=false for CPU-only runs
• override IMAGE_PATH if your .sif lives outside .docker/hpc/images/
• append any command after run.bash; bash is just the common interactive example

4. Verify Installation

Once you enter the Apptainer container, verify that everything works as expected. If you encounter any issues, please refer to the Troubleshooting guide.

Isaac Sim

Confirm that the container sees your GPU:

# Inside Apptainer container
nvidia-smi

Confirm that you can launch Isaac Sim:

# Inside Apptainer container
"$HOME/isaac-sim/isaac-sim.sh"

Note: The first launch might take a while because Isaac Sim needs to compile shaders and prepare the environment.

Space Robotics Bench

Verify that the srb command is available:

# Inside Apptainer container
srb --help
srb cache update

… continue with Basic Usage

Extras

Schedule a SLURM Job

For long-running tasks or automated workflows, you can schedule a SLURM job that will automatically run the Apptainer image. It is highly recommended that you adjust the script to your needs before submitting the job:

# HPC login node
/path/to/space_robotics_bench/.docker/hpc/submit.bash [CMD]

By default, submit.bash writes the generated job script under $HOME/jobs/, then submits it with sbatch. Its baked-in resource request is only a template; review the partition, constraint, memory, wall time, and GPU settings before using it on your cluster.