Adds docker support for orbit (#40)

# Description

Adds a directory `docker` in the root of the repo, containing a
`Dockerfile`, `dockerfile-compose.yaml`, `.env`, and utility script
`container.sh` that wraps docker-compose CLI commands. The instructions
in the documentation specify the installation steps and how to get the
Isaac Sim docker image for completeness.

To run a container, the user needs to create NGC credentials via the
NVIDIA Developers program. After that they can run the script to launch
the container:

```bash
./docker/container.sh start
./docker/container.sh enter
```

Also added an argument `-o` or `--docker` to the `orbit.sh` that calls
the above script. The above then becomes:

```bash
./orbit.sh -o start 
./orbit.sh -o enter
```

Fixes #23 

## Type of change

- New feature (non-breaking change which adds functionality)

## Checklist

- [X] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./orbit.sh --format`
- [X] I have made corresponding changes to the documentation
- [X] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file

---------
Co-authored-by: Mayank Mittal <mittalma@leggedrobotics.com>

.dockerignore

+# ignore .git related folders
+.git/
+.github/
+.gitignore
+# ignore docs
+docs/
+# ignore logs
+**/logs/
+**/runs/
+**/output/*
+**/outputs/*
+**/videos/*
+*.tmp
+# ignore docker
+docker/
+# ignore __pycache__
+**/__pycache__/
+**/*.egg-info/
+# ignore isaac sim symlink
+_isaac_sim?

docker/.env

+# Accept the NVIDIA Omniverse EULA by default
+ACCEPT_EULA=Y
+# NVIDIA Isaac Sim version to use (e.g. 2022.2.1)
+ISAACSIM_VERSION=2022.2.1
+# Derived from the default path in the NVIDIA provided Isaac Sim container
+DOCKER_ISAACSIM_PATH=/isaac-sim
+# Docker user directory - by default this is the root user's home directory
+DOCKER_USER_HOME=/root

docker/Dockerfile

+# Copyright (c) 2022, NVIDIA CORPORATION & AFFILIATES, ETH Zurich, and University of Toronto
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Nvidia Dockerfiles:
+# https://github.com/NVIDIA-Omniverse/IsaacSim-dockerfiles
+
+# Base image
+ARG ISAACSIM_VERSION
+FROM nvcr.io/nvidia/isaac-sim:${ISAACSIM_VERSION}
+
+# Adds labels to the Dockerfile
+LABEL version="1.0"
+LABEL description="Dockerfile for building and running the Orbit framework inside Isaac Sim container image."
+
+# Arguments
+# Path to Isaac Sim root folder
+ARG ISAACSIM_PATH
+
+# Set environment variables
+ENV LANG=C.UTF-8
+ENV DEBIAN_FRONTEND=noninteractive
+ENV ORBIT_PATH=/workspace/orbit
+
+# Install dependencies and remove cache
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    git \
+    ncurses-term && \
+    apt -y autoremove && apt clean autoclean && \
+    rm -rf /var/lib/apt/lists/*
+
+# FIXME: Only necessary for streaming until this fix is properly
+# rolled out by NVIDIA after Isaac Sim2023.1 release
+# Ref: https://forums.developer.nvidia.com/t/running-a-standalone-example-with-gui-in-docker-container/248147/3
+RUN sed -i 's/\("omni.isaac.quadruped"\s=\s{}\)/"omni.isaac.quadruped" = {order = 10}/g' \
+    ${ISAACSIM_PATH}/apps/omni.isaac.sim.python.kit
+
+# Copy the orbit directory
+COPY ../ ${ORBIT_PATH}
+# Delete the logs directory
+RUN rm -rf ${ORBIT_PATH}/logs
+
+# Set up a symbolic link between the installed Isaac Sim root folder and _isaac_sim in the orbit directory
+RUN ln -sf ${ISAACSIM_PATH} ${ORBIT_PATH}/_isaac_sim
+
+# installing Orbit dependencies
+RUN ${ORBIT_PATH}/orbit.sh --install --extra
+# aliasing orbit.sh and python for convenience
+RUN echo "alias orbit=${ORBIT_PATH}/orbit.sh" >> ${HOME}/.bashrc && \
+    echo "alias python=${ISAACSIM_PATH}/python.sh" >> ${HOME}/.bashrc && \
+    echo "alias python3=${ISAACSIM_PATH}/python.sh" >> ${HOME}/.bashrc && \
+    echo "alias pip='${ISAACSIM_PATH}/python.sh -m pip'" >> ${HOME}/.bashrc && \
+    echo "alias pip3='${ISAACSIM_PATH}/python.sh -m pip'" >> ${HOME}/.bashrc && \
+    echo "alias tensorboard='${ISAACSIM_PATH}/python.sh ${ISAACSIM_PATH}/tensorboard'" >> ${HOME}/.bashrc
+
+# make working directory as the orbit directory
+# this is the default directory when the container is run
+WORKDIR ${ORBIT_PATH}

docker/container.sh

+#!/bin/bash
+
+#==
+# Configurations
+#==
+
+# Exits if error occurs
+set -e
+
+# Set tab-spaces
+tabs 4
+
+# get script directory
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+#==
+# Functions
+#==
+
+# print the usage description
+print_help () {
+    echo -e "\nusage: $(basename "$0") [-h] [run] [start] [stop] -- Utility for handling docker in Orbit."
+    echo -e "\noptional arguments:"
+    echo -e "\t-h, --help         Display the help content."
+    echo -e "\tstart              Build the docker image and create the container in detached mode."
+    echo -e "\tenter              Begin a new bash process within an existing orbit container."
+    echo -e "\tcopy               Copy build and logs artifacts from the container to the host machine."
+    echo -e "\tstop               Stop the docker container and remove it."
+    echo -e "\n" >&2
+}
+
+#==
+# Main
+#==
+
+# check argument provided
+if [ -z "$*" ]; then
+    echo "[Error] No arguments provided." >&2;
+    print_help
+    exit 1
+fi
+
+# check if docker is installed
+if ! command -v docker &> /dev/null; then
+    echo "[Error] Docker is not installed! Please check the 'Docker Guide' for instruction." >&2;
+    exit 1
+fi
+
+# parse arguments
+mode="$1"
+# resolve mode
+case $mode in
+    start)
+        echo "[INFO] Building the docker image and starting the container in the background..."
+        pushd ${SCRIPT_DIR} > /dev/null 2>&1
+        docker compose --file docker-compose.yaml up --detach --build --remove-orphans
+        popd > /dev/null 2>&1
+        ;;
+    enter)
+        echo "[INFO] Entering the existing 'orbit' container in a bash session..."
+        pushd ${SCRIPT_DIR} > /dev/null 2>&1
+        docker exec --interactive --tty orbit bash
+        popd > /dev/null 2>&1
+        ;;
+    copy)
+        # check if the container is running
+        if [ "$( docker container inspect -f '{{.State.Status}}' orbit 2> /dev/null)" != "running" ]; then
+            echo "[Error] The 'orbit' container is not running! It must be running to copy files from it." >&2;
+            exit 1
+        fi
+        echo "[INFO] Copying artifacts from the 'orbit' container..."
+        echo -e "\t - /workspace/orbit/logs -> ${SCRIPT_DIR}/artifacts/logs"
+        echo -e "\t - /workspace/orbit/docs/_build -> ${SCRIPT_DIR}/artifacts/docs/_build"
+        # enter the script directory
+        pushd ${SCRIPT_DIR} > /dev/null 2>&1
+        # We have to remove before copying because repeated copying without deletion
+        # causes strange errors such as nested _build directories
+        # warn the user
+        echo -e "[WARN] Removing the existing artifacts...\n"
+        rm -rf ./artifacts/logs ./artifacts/docs/_build
+        # create the directories
+        mkdir -p ./artifacts/docs
+        # copy the artifacts
+        docker cp orbit:/workspace/orbit/logs ./artifacts/logs
+        docker cp orbit:/workspace/orbit/docs/_build ./artifacts/docs/_build
+        echo -e "\n[INFO] Finished copying the artifacts from the container."
+        popd > /dev/null 2>&1
+        ;;
+    stop)
+        echo "[INFO] Stopping the launched docker container..."
+        pushd ${SCRIPT_DIR} > /dev/null 2>&1
+        docker compose --file docker-compose.yaml down
+        popd > /dev/null 2>&1
+        ;;
+    *)
+        echo "[Error] Invalid argument provided: $1"
+        print_help
+        exit 1
+        ;;
+esac

docker/docker-compose.yaml

+services:
+  # This service is used to build the Docker image
+  # The docker image is built from the root directory
+  orbit:
+    build:
+      context: ../
+      dockerfile: docker/Dockerfile
+      args:
+        - ISAACSIM_VERSION=${ISAACSIM_VERSION}
+        - ISAACSIM_PATH=${DOCKER_ISAACSIM_PATH}
+    image: orbit
+    container_name: orbit
+    env_file:
+      - .env
+      # We set DOCKER_ISAACSIM_PATH and then forward it to ISAACSIM_PATH within
+      # the container to avoid collision with pre-existing ISAACSIM_PATH env vars
+      # that could come from installing Orbit on the local machine, causing build errors
+    environment:
+      - ISAACSIM_PATH=${DOCKER_ISAACSIM_PATH}
+      - DISPLAY=${DISPLAY}
+    volumes:
+      # These volumes follow from this page
+      # https://docs.omniverse.nvidia.com/app_isaacsim/app_isaacsim/install_faq.html#save-isaac-sim-configs-on-local-disk
+      - type: volume
+        source: isaac-cache
+        target: ${DOCKER_ISAACSIM_PATH}/kit/cache/Kit
+      - type: volume
+        source: isaac-cache
+        target: ${DOCKER_USER_HOME}/.cache/ov
+      - type: volume
+        source: isaac-cache
+        target: ${DOCKER_USER_HOME}/.cache/pip
+      - type: volume
+        source: isaac-cache
+        target: ${DOCKER_USER_HOME}/.cache/nvidia/GLCache
+      - type: volume
+        source: isaac-cache
+        target: ${DOCKER_USER_HOME}/.nv/ComputeCache
+      - type: volume
+        source: isaac-logs
+        target: ${DOCKER_USER_HOME}/.nvidia-omniverse/logs
+      - type: volume
+        source: isaac-data
+        target: ${DOCKER_USER_HOME}/.local/share/ov/data
+      - type: volume
+        source: isaac-docs
+        target: ${DOCKER_USER_HOME}/Documents
+        # These volumes allow X11 Forwarding
+      - type: bind
+        source: /tmp/.X11-unix
+        target: /tmp/.X11-unix
+      - type: bind
+        source: ${HOME}/.Xauthority
+        target: ${DOCKER_USER_HOME}/.Xauthority
+        # This overlay allows changes on the local files to
+        # be reflected within the container immediately
+      - type: bind
+        source: ../source
+        target: /workspace/orbit/source
+      - type: bind
+        source: ../docs
+        target: /workspace/orbit/docs
+        # The effect of these volumes is twofold:
+        # 1. Prevent root-owned files from flooding the _build and logs dir
+        #    on the host machine
+        # 2. Preserve the artifacts in persistent volumes for later copying
+        #    to the host machine
+      - type: volume
+        source: orbit-docs
+        target: /workspace/orbit/docs/_build/
+      - type: volume
+        source: orbit-logs
+        target: /workspace/orbit/logs
+    network_mode: host
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities: [ gpu ]
+    # This is the entrypoint for the container
+    entrypoint: bash
+    stdin_open: true
+    tty: true
+
+volumes:
+  # isaac-sim
+  isaac-cache:
+  isaac-logs:
+  isaac-data:
+  isaac-docs:
+  # orbit
+  orbit-docs:
+  orbit-logs:

docs/index.rst

@@ -35,6 +35,7 @@ If you use ``orbit`` in your work, please cite the `paper <https://arxiv.org/abs
 
    source/setup/installation
    source/setup/developer
+   source/setup/docker
    source/setup/sample
 
 .. toctree::

docs/source/setup/installation.rst

@@ -153,7 +153,7 @@ utilities to manage extensions:
 
    ./orbit.sh --help
 
-   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Orbit.
+   usage: orbit.sh [-h] [-i] [-e] [-f] [-p] [-s] [-o] [-v] [-d] [-c] -- Utility to manage extensions in Orbit.
 
    optional arguments:
       -h, --help           Display the help content.
@@ -162,6 +162,7 @@ utilities to manage extensions:
       -f, --format         Run pre-commit to format the code and check lints.
       -p, --python         Run the python executable (python.sh) provided by Isaac Sim.
       -s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
+      -o, --docker         Run the docker container helper script (docker/container.sh).
       -v, --vscode         Generate the VSCode settings file from template.
       -d, --docs           Build the documentation from source using sphinx.
       -c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'.

orbit.sh

@@ -177,7 +177,7 @@ update_vscode_settings() {
 
 # print the usage description
 print_help () {
-    echo -e "\nusage: $(basename "$0") [-h] [-i] [-e] [-f] [-p] [-s] [-v] [-d] [-c] -- Utility to manage extensions in Orbit."
+    echo -e "\nusage: $(basename "$0") [-h] [-i] [-e] [-f] [-p] [-s] [-o] [-v] [-d] [-c] -- Utility to manage extensions in Orbit."
     echo -e "\noptional arguments:"
     echo -e "\t-h, --help           Display the help content."
     echo -e "\t-i, --install        Install the extensions inside Isaac Orbit."
@@ -185,6 +185,7 @@ print_help () {
     echo -e "\t-f, --format         Run pre-commit to format the code and check lints."
     echo -e "\t-p, --python         Run the python executable (python.sh) provided by Isaac Sim."
     echo -e "\t-s, --sim            Run the simulator executable (isaac-sim.sh) provided by Isaac Sim."
+    echo -e "\t-o, --docker         Run the docker container helper script (docker/container.sh)."
     echo -e "\t-v, --vscode         Generate the VSCode settings file from template."
     echo -e "\t-d, --docs           Build the documentation from source using sphinx."
     echo -e "\t-c, --conda [NAME]   Create the conda environment for Orbit. Default name is 'orbit'."
@@ -214,6 +215,9 @@ while [[ $# -gt 0 ]]; do
             # this does not check dependencies between extensions
             export -f extract_python_exe
             export -f install_orbit_extension
+            # downgrade setuptools to avoid issues with OpenAI Gym
+            # Check the `Known Issues` section in the documentation
+            $(extract_python_exe) -m pip install --upgrade setuptools==66
             # source directory
             find -L "${ORBIT_PATH}/source/extensions" -mindepth 1 -maxdepth 1 -type d -exec bash -c 'install_orbit_extension "{}"' \;
             # unset local variables
@@ -289,6 +293,15 @@ while [[ $# -gt 0 ]]; do
             # exit neatly
             break
             ;;
+        -o|--docker)
+            # run the docker container helper script
+            docker_script=${ORBIT_PATH}/docker/container.sh
+            echo "[INFO] Running docker utility script from: ${docker_script}"
+            shift # past argument
+            bash ${docker_script} $@
+            # exit neatly
+            break
+            ;;
         -v|--vscode)
             # update the vscode settings
             update_vscode_settings