Use SUAVE with Docker

You can pull and run the exemplar as a Docker container using the following command. Keep in mind you need to have Docker installed on your computer and running.

In a terminal on your computer run:

docker run -it --shm-size=512m -p 6901:6901 -e VNC_PW=password --security-opt seccomp=unconfined ghcr.io/kas-lab/suave:main

Optionally you can add the parameter -v <absolute_path_host_compute>:/home/kasm-user/suave/results to save the results into your computer, replace <absolute_path_host_compute> with the absolute path of where you want the data to be saved in your computer, e.g:

docker run -it --shm-size=512m -v $HOME/suave_results:/home/kasm-user/suave/results -p 6901:6901 -e VNC_PW=password --security-opt seccomp=unconfined ghcr.io/kas-lab/suave:main

SEAMS2023: To use the docker image used in the SEAMS2023 paper, replace ghcr.io/kas-lab/suave:main with ghcr.io/kas-lab/suave:seams2023.

Once the container is up and running, you can interface with it through your web browser. The container will be hosted locally at the port specified, in this case 6901. So in your browser, go to http://localhost:6901.

A dialog will request a username and password, these are shown below, with the password being specifiable in the run command.

User : kasm_user
Password: password

Headless docker image

We also provide a docker image without a VNC/Web interface, so you can run experiments directly from your terminal without logging in to the web interface.

Pull image:

docker pull ghcr.io/kas-lab/suave-headless:main

Build the headless image locally from your current checkout:

docker build -t suave-headless:dev -f docker/dockerfile-suave-headless .

Non-interactive (pass command directly)

Run an experiment campaign and save results to your host machine:

docker run -it --shm-size=512m \
  -v $HOME/suave_results:/home/ubuntu-user/suave/results \
  ghcr.io/kas-lab/suave-headless:main \
  ./src/suave/runner/headless_runner.sh false metacontrol time 2

Interactive (open a shell, then run inside)

Run the local image without GPU:

docker run -it --rm --name suave_runner -e DISPLAY=$DISPLAY -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/localtime:/etc/localtime:ro suave-headless:dev

Run the local image with NVIDIA GPU support. Install the NVIDIA Container Toolkit first.

docker run -it --rm --gpus all --runtime=nvidia --name suave_runner -e DISPLAY=$DISPLAY -e QT_X11_NO_MITSHM=1 -e NVIDIA_VISIBLE_DEVICES=all -e NVIDIA_DRIVER_CAPABILITIES=all -v /dev/dri:/dev/dri -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/localtime:/etc/localtime:ro suave-headless:dev

For GUI access, prefer the SUAVE CLI’s per-container X-cookie setup:

suave docker run --image suave-headless:dev --gpu none
suave docker shell

The CLI passes display credentials without disabling X-server access control. The direct Docker examples above require separately configured X authentication for GUI use. See SUAVE CLI for display and GPU options.

Alternatively, if you dont want to use the CLI, you can set the following before starting the container (this approach is unsafe):

xhost +

Once inside the container, start an experiment with the ROS 2 runner:

ros2 run suave_runner suave_runner \
  --ros-args \
  -p gui:=False \
  -p experiments:='[
    "{\"experiment_launch\": \"ros2 launch suave_bringup mission.launch.py adaptation_manager:=bt\", \
      \"num_runs\": 2, \
      \"adaptation_manager\": \"bt\", \
      \"mission_name\": \"suave\"}"
  ]'

Build Docker images locally

To build the docker images locally, run:

./build_docker_images.sh

This builds kasm-jammy:dev, suave:dev, and suave-headless:dev from the repository root.

Development:

Run the image built locally and mount the suave folder:

From the workspace root:

docker run -it --rm --name suave --runtime=nvidia --gpus all -e DISPLAY=$DISPLAY -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/localtime:/etc/localtime:ro -v "$PWD/src/suave:/home/ubuntu-user/suave_ws/src/suave" suave-headless:dev

If you want to mount other repositories from the same ROS workspace, just add -v source_repo_path:/home/ubuntu-user/suave_ws/src/your_repo.

From the source root:

docker run -it --rm --name suave --runtime=nvidia --gpus all -e DISPLAY=$DISPLAY -e QT_X11_NO_MITSHM=1 -v /tmp/.X11-unix:/tmp/.X11-unix -v /etc/localtime:/etc/localtime:ro -v "$PWD:/home/ubuntu-user/suave_ws/src/suave" suave-headless:dev 