Add support for docker containers connected to a workspace (StoglRobo…

…tics#42)

docs/conf.py

@@ -75,6 +75,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",

docs/docker/docker_use_cases/docker_use_cases.rst

@@ -0,0 +1,18 @@
+==============================
+Use Cases with docker support
+==============================
+.. _uc-with-docker-support-index:
+
+All use cases with docker suppert are listed below. For a detailed description of the use case as well as the respective commands, you can click on the link in the use case column.
+
+.. list-table:: Overview of currently supported use cases
+   :widths: auto
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - use case
+     - docker command
+     - description
+   * - :ref:`Setup a new Workspace<uc-setup-docker-workspace>` with ``setup-ros-workspace``
+     - ``setup-ros-workspace-docker``
+     - Creates a new workspace and maps the workspace inside a docker container. You can then switch to docker using ``rtw_switch_to_docker``.

docs/docker/general_information_docker/general_information_docker.rst

@@ -0,0 +1,32 @@
+==============================
+General information on docker
+==============================
+.. _general-info-on-docker-index:
+
+Generally you can always have a look at the `docs of docker <https://docs.docker.com/>`_.
+
+Installation
+""""""""""""""""
+You have to install docker which is dependent on the operating system you are using.
+
+*   `Windows <https://docs.docker.com/desktop/windows/install/>`_
+*   `Mac <https://docs.docker.com/desktop/mac/install/>`_
+*   `Linux <https://docs.docker.com/engine/install/>`_: it depends.
+
+.. note::
+  However make sure your user is in the docker group. Check with: ``groups`` command. To add your user to the docker group run: ``sudo usermod -aG docker <username>``.
+
+Usful commands
+""""""""""""""""
+For complete list of commands have a look at `official docker cli reference <https://docs.docker.com/engine/reference/commandline/cli/>`_.
+
+* ``docker container <command>``:
+
+    * ``ls`` lists all current active containers
+    * ``ls -a`` lists all containers
+    * ``rm <container>`` removes container
+
+* ``docker image <command>``:
+
+    * ``ls`` lists all images
+    * ``rm <image>`` removes image

docs/docker/index.rst

@@ -0,0 +1,17 @@
+===========
+Docker
+===========
+.. _docker-overview:
+
+RosTeamWS supports the usage of docker containers.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   general_information_docker/*
+   docker_use_cases/*
+   supported_versions/*
+
+.. note::
+  If you want to forward a xsession from docker (e.g. rviz2), you have to install xhost.

docs/docker/supported_versions/supported_versions.rst

@@ -0,0 +1,24 @@
+=============================================
+Supported ros versions and operating systems
+=============================================
+.. _supported-os-ros-docker-versions-index:
+
+For the supported Ubuntu and ros version combinations have a look at the table below.
+
+.. list-table:: Supported Ubuntu and ros versions combinations are marked with an X.
+   :widths: auto
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - ros version
+     - ubuntu 20.04
+     - ubuntu 22.04
+   * - foxy
+     - X
+     -
+   * - galactic
+     - X
+     -
+   * - rolling
+     - X
+     - X

docs/faq/index.rst

@@ -0,0 +1,14 @@
+================================
+FAQ
+================================
+
+On Docker
+----------------
+
+How to forward a xsession
+"""""""""""""""""""""""""""""
+If you want to forward a xsession from docker (e.g. rviz2), you have to install xhost. When executing the commands ``start_container`` the docker user is added to the X Server access list.
+
+sudo: unable to resolve host <hostname>: Name or service not known
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Problem using sudo: If you encounter following message trying to use sudo: ``sudo: unable to resolve host <hostname>: Name or service not known``. You have to add ``127.0.0.1 <hostname>`` to the ``/etc/hosts`` file inside the container. However, using sudo should work fine without adding it.

docs/index.rst

@@ -53,3 +53,5 @@ The opinions and proposals stated here are merely related to the authors' experi
    getting_started/index.rst
    guidelines/index.rst
    use-cases/index.rst
+   docker/index.rst
+   faq/index.rst

docs/use-cases/operating_system/create_setup_workspace.rst

@@ -3,7 +3,10 @@ Setup a new Workspace
 ===========================
 .. _uc-setup-workspace:
 
-This use-case describes how to setup a new ROS workspace using scripts from the ROS Team Workspace (RosTeamWS) framework.
+This use-case describes how to setup a new ROS workspace using scripts from the ROS Team Workspace (RosTeamWS) framework. Besides the creation of a local workspace, creation of a Ubuntu based docker container is supported. For more details have a look below in the `Docker workspace`_ section.
+
+Local workspace
+----------------
 
 ``setup-ros-workspace`` accepts ros distro name workspace suffix and workspace folder as parameters.
 All three parameters are optional.
@@ -17,3 +20,48 @@ All three parameters are optional.
 The script creates in the ``$HOME/<WS_FOLDER>`` a new ROS workspace with name ``ros_ws_<WS_PREFIX>_<ROS_DISTRO>_<WS_SUFFIX>``.
 If you want to omit any of input parameters use ``"-"`` as argument.
 Default value for ``<WS_FOLDER>`` is "workspace".
+
+.. _uc-setup-docker-workspace:
+
+Docker workspace
+------------------
+
+.. code-block:: bash
+   :caption: How to setup a workspace inside a docker container.
+   :name: setup docker workspace
+
+   setup-ros-workspace-docker ROS_DISTRO WS_FOLDER WS_PREFIX WS_SUFFIX.
+
+Like the script ``setup-ros-workspace`` the ``setup-ros-workspace-docker`` creates a new local ROS workspace. Then a Ubuntu docker container gets built and the created workspace is mounted inside the docker container under the home directory. The first time a docker container is build can take quite a while. When the first build is finished you are directly connected as user inside the container. You can verify this by checking if your hostname has changed. To exit a container simply type the ``exit`` command.
+
+Reconnect to a container
+""""""""""""""""""""""""""
+
+If you exited a container an want to reconnect as a user, you have to run the ``rtw_switch_to_docker`` command. However before executing this you have to source your workspace with ``_<workspace_alias_command>``. If you want to connect as a root user you can execute ``rtw_switch_to_docker_root``.
+
+Recreate a container
+""""""""""""""""""""""
+
+If you removed an image,  you can recreate it by switching into the ``.rtw_docker_defines`` folder inside your workspace and then executing the ``.\build_docker_image`` command. After the container is rebuilt, you can create it with ``.\create_docker_container`` command. Thereafter, you should be able to normally start, reconnect and stop the container.
+
+.. note::
+  For more general questions on the usage of docker and the limitations of RosTeamWS in interacting with docker have a look at our :ref:`docker related docs<docker-overview>`.
+
+CLI overview
+"""""""""""""
+
+.. list-table:: Overview of the cli
+   :widths: auto
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - command
+     - description
+   * - ``setup-ros-workspace-docker``
+     - Creates a new workspace and maps the workspace inside a docker container. You can then switch to docker using ``rtw_switch_to_docker``.
+   * - ``rtw_switch_to_docker``
+     - Starts the docker container if it has been stopped and connects to the container as user.
+   * - ``rtw_switch_to_docker_root``
+     - Starts the docker container if it has been stopped and connects to the container as root-user.
+   * - ``rtw_stop_docker``
+     - Stops the docker container.

scripts/_RosTeamWs_Defines.bash

@@ -55,9 +55,12 @@ function RosTeamWS_setup_exports {
   export RAW_TERMINAL_COLOR_LIGHT_GRAY=$'\e[0;37m'
   export RAW_TERMINAL_COLOR_WHITE=$'\e[1;37m'
 
+  ## Define semantics of each color
   export TERMINAL_COLOR_USER_NOTICE=${TERMINAL_COLOR_YELLOW}
   export TERMINAL_COLOR_USER_INPUT_DECISION=${TERMINAL_COLOR_PURPLE}
   export TERMINAL_COLOR_USER_CONFIRMATION=${TERMINAL_COLOR_BLUE}
+  export RTW_COLOR_NOTIFY_USER=${TERMINAL_COLOR_YELLOW}
+  export RTW_COLOR_ERROR=${TERMINAL_COLOR_RED}
 }
 
 # TODO(denis): add this into setup.bash
@@ -224,21 +227,25 @@ function print_and_exit {
 
   message=$1
   echo ""
-  echo -e "${TERMINAL_COLOR_RED}$message  !!Exiting...${TERMINAL_COLOR_NC}"
+  echo -e "${RTW_COLOR_ERROR}$message!!! Exiting...${TERMINAL_COLOR_NC}"
   if [ ! -z "$2" ]; then
     echo ""
-    echo -e "${TERMINAL_COLOR_YELLOW}Usage: '$2'${TERMINAL_COLOR_NC}"
+    echo -e "${TERMINAL_COLOR_USER_NOTICE}Usage: '$2'${TERMINAL_COLOR_NC}"
   fi
-  echo -e "${TERMINAL_COLOR_BLUE}Error has happened. Press <CTRL> + C two times...${TERMINAL_COLOR_NC}"
+  echo -e "${TERMINAL_COLOR_USER_CONFIRMATION}Error has happened. Press <CTRL> + C two times...${TERMINAL_COLOR_NC}"
   read -p ""
-  throw_error
+  exit 1
 }
 
 function framework_default_paths {
   ros_distro=$1
 
   FRAMEWORK_NAME="ros_team_workspace"
-  FRAMEWORK_BASE_PATH=${FRAMEWORK_BASE_PATH:=/opt/RosTeamWS}
+
+  # if we suppose a structure like
+  # /opt/RosTeamWS/ros_ws_<ros_distro>/src/ros_team_ws/...
+  # then FRAMEWORK_BASE_PATH should be /opt/RosTeamWS/
+  FRAMEWORK_BASE_PATH="$(RosTeamWS_script_own_dir)/../../../.."
   FRAMEWORK_PACKAGE_PATH="$FRAMEWORK_BASE_PATH/ros_ws_$ros_distro/src/$FRAMEWORK_NAME"
 
   if [ ! -d "$FRAMEWORK_PACKAGE_PATH" ]; then
@@ -253,19 +260,24 @@ function framework_default_paths {
   ROS2_CONTROL_HW_ITF_TEMPLATES="$ROS2_CONTROL_TEMPLATES/hardware"
   ROS2_CONTROL_CONTROLLER_TEMPLATES="$ROS2_CONTROL_TEMPLATES/controller"
   LICENSE_TEMPLATES="$FRAMEWORK_PACKAGE_PATH/templates/licenses"
+  DOCKER_TEMPLATES="$FRAMEWORK_PACKAGE_PATH/templates/docker"
 }
 
 function check_ros_distro {
   ros_distro=$1
   if [ -z "$1" ]; then
-    ros_distro=$DEFAULT_ROS_DISTRO
-    echo "No ros_distro defined. Using default: '$ros_distro'"
-    if [ ! -d "/opt/ros/$ros_distro" ]; then
-      print_and_exit "FATAL: ROS '$ros_distro' not installed on this computer! Exiting..."
-#             echo "FATAL: ROS '$ros_distro' not installed on this computer! Exiting..."
-#             exit
+    if [ -n "$DEFAULT_ROS_DISTRO" ]; then
+      ros_distro=$DEFAULT_ROS_DISTRO
+      echo "No ros_distro defined. Using default: '$ros_distro'"
+      if [ ! -d "/opt/ros/$ros_distro" ]; then
+        print_and_exit "FATAL: ROS '$ros_distro' not installed on this computer! Exiting..."
+  #             echo "FATAL: ROS '$ros_distro' not installed on this computer! Exiting..."
+  #             exit
+      fi
+      read -p "Press <ENTER> to continue or <CTRL>+C to exit."
+    else
+      return 2>/dev/null
     fi
-    read -p "Press <ENTER> to continue or <CTRL>+C to exit."
   fi
 
   if [ ! -d "/opt/ros/$ros_distro" ]; then
@@ -279,6 +291,8 @@ function check_ros_distro {
     ros_version=2
   elif [[ $ros_distro == "galactic" ]]; then
     ros_version=2
+  elif [[ $ros_distro == "humble" ]]; then
+    ros_version=2
   elif [[ $ros_distro == "rolling" ]]; then
     ros_version=2
   elif [[ $ros_distro == "noetic" ]]; then
@@ -314,4 +328,4 @@ function compile_and_source_package {
 
 # END: Framework functions
 
-FRAMEWORK_MAIN_PATH="$(RosTeamWS_script_own_dir)/../"
+FRAMEWORK_MAIN_PATH="$(RosTeamWS_script_own_dir)/.."

scripts/_RosTeamWs_Docker_Defines.bash

@@ -14,4 +14,34 @@
 
 ## BEGIN: Default RosTeamWS Docker Definitions and Aliases
 
-# function _run_docker()
+setup-ros-workspace-docker () {
+   source "$RosTeamWS_FRAMEWORK_SCRIPTS_PATH"/setup-ros-workspace.bash
+   create_workspace_docker "$@"
+}
+
+rtw_switch_to_docker () {
+  if [ -z "$RosTeamWS_WS_DOCKER_SUPPORT" ] || [ "$RosTeamWS_WS_DOCKER_SUPPORT" == false ]; then
+    print_and_exit"It seems your current workspace does not support docker. If it should, did you activate it by executing _\"<ws_alias>\"?"
+  fi
+
+  source "$RosTeamWS_FRAMEWORK_SCRIPTS_PATH"/docker/_RosTeamWs_Docker_Defines.bash
+  start_and_connect_user_to_docker "$RosTeamWS_DOCKER_TAG"
+}
+
+rtw_switch_to_docker_root () {
+  if [ -z "$RosTeamWS_WS_DOCKER_SUPPORT" ] || [ "$RosTeamWS_WS_DOCKER_SUPPORT" == false ]; then
+    print_and_exit "It seems your current workspace does not support docker. If it should, did you activate it by executing _\"<ws_alias>\"?"
+  fi
+
+  source "$RosTeamWS_FRAMEWORK_SCRIPTS_PATH"/docker/_RosTeamWs_Docker_Defines.bash
+  start_and_connect_root_to_docker "$RosTeamWS_DOCKER_TAG"
+}
+
+rtw_stop_docker () {
+  if [ -z "$RosTeamWS_WS_DOCKER_SUPPORT" ] || [ "$RosTeamWS_WS_DOCKER_SUPPORT" == false ]; then
+    print_and_exit "It seems your current workspace does not support docker. If it should, did you activate it by executing _\"<ws_alias>\"?"
+  fi
+
+  source "$RosTeamWS_FRAMEWORK_SCRIPTS_PATH"/docker/_RosTeamWs_Docker_Defines.bash
+  stop_docker_container "$RosTeamWS_DOCKER_TAG"
+}

scripts/_Team_Defines.bash

@@ -12,28 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-## BEGIN: Team specific definitions
-
-DEFAULT_ROS_DISTRO="rolling"
-DEFAULT_ROS_VERSION=2
+## BEGIN: definitions
 
 # TODO(denis): We have two example teams. On is working with industrial and other with mobile robots
 # TEAM_TEAM_NAMES=("Industrial" "Mobile")
 
-TEAM_LICENSE="Apache-2.0"
-
-TEAM_REPOSITORY_SERVER="https://github.com"
-
-TEAM_PRIVATE_CONFIG_PATH=""
-
 # Define a path to a repository with your internal assets and configurations
 TEAM_INTERNAL_ASSETS="/opt/RosTeamWS/assets/"
 
 ## END: definitions
 
 # TODO(denis): implement here support for internal repos
-source $TEAM_INTERNAL_ASSETS/setup.bash
-
+if [ -f $TEAM_INTERNAL_ASSETS/setup.bash ]; then
+  source $TEAM_INTERNAL_ASSETS/setup.bash
+fi
 
 ## BEGIN: Framework definition adjustable by users
 # TBD
@@ -62,7 +54,6 @@ alias setup_ros2_aliases=RosTeamWS_setup_ros2_aliases
 
 # BEGIN: Define aliases for standard scripts
 # Change those to your custom ones you would like to use.
-
 alias create-new-package=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/create-new-package.bash
 
 alias setup-repository=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/setup-repository.bash
@@ -71,6 +62,11 @@ alias setup-repository-ci=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/setup-ci-config.bash
 
 alias setup-ros-workspace=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/setup-ros-workspace.bash
 
+setup-ros-workspace () {
+  source "$RosTeamWS_FRAMEWORK_SCRIPTS_PATH"/setup-ros-workspace.bash
+  create_workspace "$@"
+}
+
 alias setup-robot-bringup=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/setup-robot-bringup.bash
 
 alias setup-robot-description=$RosTeamWS_FRAMEWORK_SCRIPTS_PATH/setup-robot-description.bash