|
| 1 | +# Docker Profiles |
| 2 | + |
| 3 | +This directory contains multiple examples to build and run Hydra with different Docker configurations. |
| 4 | + |
| 5 | +## Requirements |
| 6 | +You will need `git`, `make`, and `vcstool` as well as [docker](https://docs.docker.com/engine/install/ubuntu/) and the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) for the profiles with GPU support. You may need to run `sudo usermod -aG docker $USER` + `newgrp docker` after installing docker, and similarly, you may need to run `sudo systemctl restart docker` after installing the toolkit. |
| 7 | + |
| 8 | +## Profiles |
| 9 | + |
| 10 | +- **`minimal`** (no GPU support): |
| 11 | + - ROS 2 Jazzy |
| 12 | + - Basic ROS dev tools and C++ dependencies |
| 13 | +- **`dev`**: |
| 14 | + - ROS 2 Jazzy |
| 15 | + - Basic ROS dev tools and C++ dependencies |
| 16 | + - CUDA 12.8 |
| 17 | + - TensorRT |
| 18 | +- **`zed`**: |
| 19 | + - ROS 2 Jazzy |
| 20 | + - Basic ROS dev tools and C++ dependencies |
| 21 | + - CUDA 12.8 |
| 22 | + - ZED SDK |
| 23 | + - TensorRT |
| 24 | + |
| 25 | +## Commands |
| 26 | + |
| 27 | +The Makefile supports the following commands: |
| 28 | + |
| 29 | +| Command | Description | |
| 30 | +|---------------|--------------------------------------------------------| |
| 31 | +| `make build` | Builds the selected profile (must set `PROFILE=...`) | |
| 32 | +| `make run` | Runs an interactive container (auto-removed) | |
| 33 | +| `make up` | Runs container in background | |
| 34 | +| `make shell` | Opens a shell inside a running container | |
| 35 | +| `make stop` | Stops a running container | |
| 36 | +| `make start` | Starts a stopped container | |
| 37 | +| `make down` | Stops and removes a container | |
| 38 | +| `make clean` | Prunes unused containers and images | |
| 39 | + |
| 40 | + |
| 41 | +> :grey_exclamation: **Note**</br> |
| 42 | +> You must specify the profile you want to use by setting the `PROFILE` variable when running the commands (e.g., `make build PROFILE=minimal`). If you don't want to type `PROFILE=<profile>` every time, you can set the `PROFILE` environment variable in your shell via `export PROFILE=<profile>`. This will make the Makefile use that profile by default. |
| 43 | +
|
| 44 | +--- |
| 45 | + |
| 46 | +## Quick Start (PROFILE=minimal) |
| 47 | +The following instructions will guide you through setting up and running Hydra using Docker with the `minimal` profile. The `minimal` profile does not provide CUDA/TensorRT support. |
| 48 | + |
| 49 | +Before starting, export the `WORKSPACE` environment variable to point to your Hydra workspace directory (e.g., `export WORKSPACE=/path/to/hydra_ws`). This is only needed for copy/pasting the commands in the quick start. |
| 50 | + |
| 51 | +### Host (PROFILE=minimal) |
| 52 | +Before using Docker, make sure to: |
| 53 | + |
| 54 | +1. Setup your workspace: |
| 55 | + |
| 56 | + ```shell |
| 57 | + mkdir -p $WORKSPACE/src |
| 58 | + cd $WORKSPACE |
| 59 | + echo "build: {cmake-args: [--no-warn-unused-cli, -DCMAKE_BUILD_TYPE=Release, -DCONFIG_UTILS_ENABLE_ROS=OFF]}" > colcon_defaults.yaml |
| 60 | + |
| 61 | + cd src |
| 62 | + git clone https://github.com/MIT-SPARK/Hydra-ROS.git hydra_ros |
| 63 | + |
| 64 | + #replace ros2.yaml with ros2_docker.yaml to use https |
| 65 | + vcs import . < hydra_ros/install/ros2.yaml |
| 66 | + ``` |
| 67 | + |
| 68 | +> :warning: **Warning**</br> |
| 69 | +> In the `vcs import` step, GitHub may block too many concurrent requests. If you receive `kex_exchange_identification: read: Connection reset by peer` errors, try running `vcs import . < hydra/install/hydra.rosinstall --workers 1`. |
| 70 | + |
| 71 | +2. You can skip this step if you do not need to mount a dataset path from the host; otherwise, setup your dataset path (this only needs to be done once): |
| 72 | + |
| 73 | + ```shell |
| 74 | + cd $WORKSPACE/src/hydra_ros/docker |
| 75 | + echo "DATASETS_PATH=/home/jared/datasets" > .env |
| 76 | + ``` |
| 77 | + |
| 78 | +If you want to change the dataset path, you do not need to rebuild the image; you can simply edit the `.env` file in the `docker` directory and restart the container (e.g., `make down` + `make up`). The path will be mounted to `/root/data` inside the container. |
| 79 | + |
| 80 | +3. If running the minimal profile, you can run Hydra on the uhumans2 dataset. Download the ROS 1 bag for the office scene [here](https://drive.google.com/file/d/1awAzQ7R1hdS5O1Z2zOcpYjK7F4_APq_p/view?usp=drive_link). The ROS 1 bag will need to be converted to ROS 2 bag (see below). |
| 81 | + |
| 82 | +### Container (PROFILE=minimal) |
| 83 | +1. Build the image and run the container for the `minimal` profile: |
| 84 | + |
| 85 | +```shell |
| 86 | +cd $WORKSPACE/src/hydra_ros/docker |
| 87 | +make build PROFILE=minimal |
| 88 | +make up PROFILE=minimal |
| 89 | +make shell PROFILE=minimal |
| 90 | +``` |
| 91 | + |
| 92 | +Once inside the container, you can build and run Hydra (you should already be in `/root/hydra_ws` when opening the shell): |
| 93 | + |
| 94 | +```bash |
| 95 | +colcon build --symlink-install --continue-on-error |
| 96 | +source install/setup.bash |
| 97 | +ros2 launch hydra_ros uhumans2.launch.yaml |
| 98 | +``` |
| 99 | + |
| 100 | + |
| 101 | +> **:warning: Warning**<br> |
| 102 | +> If you encounter graphical issues (e.g. rviz not displaying), make sure you run `xhost +local:root` on the host machine and that `DISPLAY` is correctly set. |
| 103 | + |
| 104 | +2. In a separate terminal, open another shell in the container: |
| 105 | + |
| 106 | +```bash |
| 107 | +cd $WORKSPACE/src/hydra_ros/docker |
| 108 | +make shell PROFILE=minimal |
| 109 | +``` |
| 110 | + |
| 111 | +Before playing the bag, make sure to create an override for latching static tf topics, then play the bag: |
| 112 | + |
| 113 | +```bash |
| 114 | +echo "/tf_static: {depth: 1, durability: transient_local}" > ~/.tf_overrides.yaml |
| 115 | +ros2 bag play /root/data/path/to/rosbag --clock --qos-profile-overrides-path ~/.tf_overrides.yaml |
| 116 | +``` |
| 117 | + |
| 118 | + |
| 119 | +> **:warning: Warning**<br> |
| 120 | +> You must convert the ROS 1 bag to a ROS 2 bag before playing it. The `rosbags-convert` tool is preinstalled in the container, and you can use it to convert the bag using the following command: `rosbags-convert --src path/to/office.bag --dst path/to/office` (in ROS2, you do not need `.bag` since a ROS 2 bag is a directory). You should run this in the container if you don't have `rosbags-convert` installed on your host machine. |
| 121 | +
|
| 122 | +## Quick Start (PROFILE=zed) |
| 123 | +
|
| 124 | +### Host (PROFILE=zed) |
| 125 | +You can repeat the steps above using the `zed` profile instead of `minimal`, but you must complete a few additional steps on the host to run with hardware. |
| 126 | +
|
| 127 | +1. Add the `zed-ros2-wrapper` to your workspace, and the dependencies will be installed automatically via the dockerfile (if you forget this step, you must rebuild the image): |
| 128 | +
|
| 129 | +```shell |
| 130 | +cd $WORKSPACE/src |
| 131 | +git clone https://github.com/stereolabs/zed-ros2-wrapper.git |
| 132 | +``` |
| 133 | +
|
| 134 | +2. While the uhumans2 dataset has pre-segmented images, you must run semantic segmentation on the images. You can use [semantic_inference](https://github.com/MIT-SPARK/semantic_inference), which should already be installed via `ros2.yaml`. Download the default [pretrained model](https://drive.google.com/file/d/1XRcsyLSvqqhqNIaOI_vmqpUpmBT6gk9-/view?usp=drive_link) to the directory `$WORKSPACE/.models/`. |
| 135 | +
|
| 136 | +3. (optional) To avoid re-optimizing the model when running the container, set the `ZED_CACHE` environment variable to mount a host directory for the zed cache: |
| 137 | +
|
| 138 | +```shell |
| 139 | +mkdir -p "$WORKSPACE/.zed_cache" |
| 140 | +
|
| 141 | +cd $WORKSPACE/src/hydra_ros/docker |
| 142 | +grep -q '^ZED_CACHE=' .env || echo "ZED_CACHE=$WORKSPACE/.zed_cache" >> .env |
| 143 | +``` |
| 144 | +### Container (PROFILE=zed) |
| 145 | +
|
| 146 | +Once inside the container, you can build and run Hydra for the zed profile (you should already be in `/root/hydra_ws` when opening the shell): |
| 147 | +
|
| 148 | +```shell |
| 149 | +colcon build --symlink-install --continue-on-error |
| 150 | +source install/setup.bash |
| 151 | +ros2 launch hydra_ros zed2i.launch.yaml |
| 152 | +``` |
| 153 | +
|
| 154 | +## CUDA/TensorRT Support (PROFILE=dev) |
| 155 | +In general, you can start from the `dev` profile for development if you need CUDA and TensorRT support with Hydra (e.g., required to use [semantic_inference](https://github.com/MIT-SPARK/semantic_inference) with Hydra). You can reuse the same steps from the `minimal` profile to setup the host machine adding your software/hardware dependencies. |
| 156 | +
|
| 157 | +### Example with D455/T265 |
| 158 | +Here, we provide another example of running Hydra with a bag recorded with a sensor payload (mounted on an `a1` quadruped) using a D455 for color/depth and T265 for visual odometry (refer to this [launch](../hydra_ros/launch/datasets/a1.launch.yaml) and [config](../hydra_ros/config/datasets/a1.yaml)), which runs with the following commands: |
| 159 | +
|
| 160 | +1. Run the `a1` launch script for Hydra: |
| 161 | +```bash |
| 162 | +ros2 launch hydra_ros a1.launch.yaml use_sim_time:=true |
| 163 | +``` |
| 164 | +
|
| 165 | +2. Run the bag: |
| 166 | +```bash |
| 167 | +ros2 bag play /path/to/bag --clock --exclude-topics /tf_static |
| 168 | +``` |
| 169 | +> :grey_exclamation: **Note**</br> |
| 170 | +> The static tfs are included in the launch script for the `a1`, so you should exclude them when playing the bag. |
0 commit comments