Change Existing and Add New Docker* Images to the EI for AMR SDK#

This tutorial covers:

Creating custom Docker* images by adding or removing components in the Docker* files provided in the SDK
Creating completely new Docker* images by selecting components from the Docker* files provided in the SDK

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.

Create a Customized Docker* Image#

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
```
Go to the docker_stages folder, and choose the dockerfile.stage.* you want to modify:
```
cd docker_stages
```

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 #####################################

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*/AMR_containers
source ./01_docker_sdk_env/docker_compose/common/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.

To see the details of the built images:

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

Run the required, newly-installed application from within the container (see Turtlesim 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.

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/*

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 ########################################

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 #######################################

Define a new target in the docker_compose/01_amr/amr-sdk.all.yml or docker_compose/01_amr/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.']

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*/AMR_containers
source ./01_docker_sdk_env/docker_compose/common/docker_compose.source
docker compose -f 01_docker_sdk_env/docker_compose/01_amr/amr-sdk.all.yml build imaginary ros2-foxy-sdk

To see the details of the built image:

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

To verify that the imaginary component is part of created Docker* image:
```
docker history amr-ubuntu2004-ros2-foxy-imaginary
```
Run the required, newly-installed application from within the container (see Turtlesim for details).

Troubleshooting#

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]:

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.

Change Existing and Add New Docker* Images to the EI for AMR SDK

Contents

Change Existing and Add New Docker* Images to the EI for AMR SDK#

Create a Customized Docker* Image#

Create New Docker* Images with Selected Applications from the SDK#

Troubleshooting#