Create a Customized Docker* Image

1. In the SDK root folder, go to the Docker* environment folder:

   cd <edge_insights_for_amr_path>/Edge_Insights_for_Autonomous_Mobile_Robots_*/AMR_containers/01_docker_sdk_env/

   There are two main Docker* files here:

   • dockerfile.amr: For images to be deployed on robots

   • dockerfile.edge-server: For images to be deployed on the server

   These Docker* files create multiple Docker* images. The Docker* images to be created are defined in the yaml configuration file, which is in the docker_compose folder.

   Also, these Docker* files include many sub-files in the docker_stages folder. Each Docker* stage represents a specific component that must be included in one of the Docker* images.

   # docker_compose and docker_stages folders and dockerfiles are found as below.
   ls -a ./
   .  ..  artifacts  docker_compose  docker_orchestration  docker_stages  dockerfile.amr  dockerfile.edge-server

2. Go to the docker_stages folder, and choose the dockerfile.stage.* you want to modify:

   cd docker_stages

3. Open the Docker* file from the environment folder in your preferred integrated development environment (IDE), and append component-specific installation instructions in the appropriate place.

   The following is an example of appending the Gazebo* application in dockerfile.stage.realsense.

   Give appropriate permissions:

   chmod 777 dockerfile.stage.realsense

   ... <original code from dockerfile.stage.realsense>
   
   
   ################################# Gazebo app START #####################################
   RUN sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'   \
       && wget https://packages.osrfoundation.org/gazebo.key -O - |  apt-key add -                                                                     \
       && apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -q -y                                               \
          ros-${ROS_DISTRO}-gazebo-ros-pkgs                                                                                                           \
       && rm -rf /var/lib/apt/lists/*
   ################################# Gazebo app END #####################################

4. Build the Docker* image with the modified Docker* file:

   Choose the appropriate Docker* Compose target from the docker_compose folder, so that your particular target Docker* image is built.

   For example, to build Intel® RealSense™:

   cd <edge_insights_for_amr_path>/Edge_Insights_for_Autonomous_Mobile_Robots_202*
   source 01_docker_sdk_env/docker_compose/05_tutorials/config/docker_compose.source
   docker-compose -f 01_docker_sdk_env/docker_compose/01_amr/amr-sdk.all.yml build realsense

   NOTE:

   Building should be done on a development machine with at least 16 GB of RAM. Building multiple Docker* images, in parallel, on a system with 8 GB of RAM may end in a crash due to lack of system resources.

   Building on the People’s Republic of China (PRC) network may result in multiple issues. See the Troubleshooting section for more details.

5. To see the details of the built images:

   docker images | grep -i amr-
   docker images | grep -i edge-server-

6. Run the required, newly-installed application from within the container (see Run a ROS 2 Sample Application in the Docker* Container for details).

Create New Docker* Images with Selected Applications from the SDK

In this tutorial, you install an imaginary component as a new image and add it to the existing ros2-foxy-sdk image.

1. Add a new file called docker_stages/01_amr/dockerfile.stage.imaginary.

   Add instructions to install this component into this file using basic Docker* file syntax:

   # Note: below repo does not exist, it is for demonstration purposes only
   WORKDIR ${ROS2_WS}
   RUN cd src                                                           \
      && git clone --branch ros2 https://github.com/imaginary.git       \
      && cd imaginary && git checkout <commit_id>                       \
      && source ${ROS_INSTALL_DIR}/setup.bash                           \
      && colcon build --install-base ${ROS2_WS}/install                 \
      && rm -rf ${ROS2_WS}/build/* ${ROS2_WS}/src/* ${ROS2_WS}/log/*

2. Include this new Docker* file in dockerile.amr or dockerfile.edge-server at any appropriate location.

   You need to create a separate stage for this new Docker* file so that a separate image can be created using that stage name. For example, append this to dockerfile.amr:

   ################################### imaginary stage START ######################################
   FROM ros-base AS imaginary
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.imaginary
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.entrypoint
   ################################### imaginary stage END ########################################

3. If you need to add this new component to other images also, add it inside any stage.

   For example, to add imaginary to the ros2-foxy-sdk stage:

   ################################# ros2-foxy-SDK stage START ####################################
   FROM ros-base AS ros2-foxy-sdk
   INCLUDE+ docker_stages/common/dockerfile.stage.tools-dev
   
   ####### add new component on appropriate place in this block #######
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.imaginary
   
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.vda5050
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.imaginary
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.opencv
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.rtabmap
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.fastmapping
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.gazebo
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.gstreamer
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.kobuki
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.nav2
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.realsense
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.ros-arduino
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.ros1-bridge
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.rplidar
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.turtlebot3
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.turtlesim
   # simlautions has hard dependency in nav2 (@todo:), so we can not create separate image for simulations without nav2.
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.simulations
   INCLUDE+ docker_stages/01_amr/dockerfile.stage.entrypoint
   ################################# ros2-foxy-SDK stage END #######################################

4. Define a new target in the docker_compose/amr-sdk.all.yml or docker_compose/edge-server.all.yml file:

   imaginary:
       image: ${REPO_URL}amr-ubuntu2004-ros2-foxy-imaginary:${DOCKER_TAG:-latest}
       container_name: ${CONTAINER_NAME_PREFIX:-amr-sdk-}imaginary
       extends:
          file: ./amr-sdk.all.yml
          service: ros-base
       build:
          target: imaginary
       network_mode: host
       command: ['echo imaginary run finished.']

5. Build two Docker* images:

   • amr-ubuntu2004-ros2-foxy-imaginary

   • amr-ubuntu2004-ros2-foxy-sdk

   These images contain the new imaginary component.

   cd <edge_insights_for_amr_path>/Edge_Insights_for_Autonomous_Mobile_Robots_202*
   source 01_docker_sdk_env/docker_compose/05_tutorials/config/docker_compose.source
   docker-compose -f 01_docker_sdk_env/docker_compose/01_amr/amr-sdk.all.yml build imaginary ros2-foxy-sdk

6. To see the details of the built image:

   docker images | grep -i amr-
   docker images | grep -i imaginary

7. To verify that the imaginary component is part of created Docker* image:

   docker history amr-ubuntu2004-ros2-foxy-imaginary

8. Run the required, newly-installed application from within the container (see Run a ROS 2 Sample Application in the Docker* Container for details).

Troubleshooting

1. Building on the People’s Republic of China (PRC) Open Network.

   Building Docker* images on the People’s Republic of China (PRC) open network may fail. Intel recommends updating these links with their corresponding PRC mirrors. To do this, go to the AMR_containers folder, and update the broken sites with the default or user-defined mirrors.

   cd Edge_Insights_for_Autonomous_Mobile_Robots_*/AMR_containers
   chmod 775 changesources.sh
   ./changesources.sh -d .
   Enter mirror server ('https://example.com' format) or leave empty to use the default value.
   Git mirror [https://github.com.cnpmjs.org]:
   Apt mirror [http://mirrors.bfsu.edu.cn]:
   Pip mirror [https://opentuna.cn/pypi/web/simple/]:
   Raw files mirror [https://raw.staticdn.net]:

2. Building on a limited resource system (8 GB of RAM or less) can be problematic.

   Perform the following steps to minimize issues:

   1. Save the output in a file instead of printing it, because printing consumes RAM resources.

      nohup time docker-compose -f 01_docker_sdk_env/docker_compose/01_amr/amr-sdk.all.yml build --parallel > eiforAMR.txt &

      NOTE:

      Edge Insights for Autonomous Mobile Robots comes with prebuilt images and building all images is not required. Only do this step if you want to regenerate all images.

   2. For remote connections, use an ssh connection instead of a VNC one as VNC connection consumes resources.

   3. For building multiple Docker* images, do not use the --parallel option as it requires more resources.

      nohup time docker-compose -f 01_docker_sdk_env/docker_compose/01_amr/amr-sdk.all.yml build > eiforAMR.txt &

      NOTE:

      Edge Insights for Autonomous Mobile Robots comes with prebuilt images and building all images is not required. Only do this step if you want to regenerate all images.