Docker tutorial

readme.md

@@ -31,7 +31,7 @@ The librealsense port in vcpkg is kept up to date by Microsoft team members and
 ## Download and Install
 * **Download** - The latest releases including the Intel RealSense SDK, Viewer and Depth Quality tools are available at: [**latest releases**](https://github.com/IntelRealSense/librealsense/releases). Please check the [**release notes**](https://github.com/IntelRealSense/librealsense/wiki/Release-Notes) for the supported platforms, new features and capabilities, known issues, how to upgrade the Firmware and more.
 
-* **Install** - You can also install or build from source the SDK (on [Linux](./doc/distribution_linux.md) \ [Windows](./doc/distribution_windows.md) \ [Mac OS](doc/installation_osx.md) \ [Android](./doc/android.md)), connect your D400 depth camera and you are ready to start writing your first application.
+* **Install** - You can also install or build from source the SDK (on [Linux](./doc/distribution_linux.md) \ [Windows](./doc/distribution_windows.md) \ [Mac OS](doc/installation_osx.md) \ [Android](./doc/android.md) \ [Docker](./scripts/Docker/readme.md)), connect your D400 depth camera and you are ready to start writing your first application.
 
 > **Support & Issues**: If you need product support (e.g. ask a question about / are having problems with the device), please check the [FAQ & Troubleshooting](https://github.com/IntelRealSense/librealsense/wiki/Troubleshooting-Q%26A) section.
 > If not covered there, please search our [Closed GitHub Issues](https://github.com/IntelRealSense/librealsense/issues?utf8=%E2%9C%93&q=is%3Aclosed) page,  [Community](https://communities.intel.com/community/tech/realsense) and [Support](https://www.intel.com/content/www/us/en/support/emerging-technologies/intel-realsense-technology.html) sites.

scripts/Docker/Dockerfile

@@ -0,0 +1,76 @@
+ARG BASE_IMAGE=ubuntu:20.04 
+#################################
+#   Librealsense Builder Stage  #
+#################################
+FROM $BASE_IMAGE as librealsense-builder
+
+ARG LIBRS_VERSION
+# Make sure that we have a version number of librealsense as argument
+RUN test -n "$LIBRS_VERSION"
+
+# To avoid waiting for input during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Builder dependencies installation
+RUN apt-get update \
+    && apt-get install -qq -y --no-install-recommends \
+    build-essential \
+    cmake \
+    git \
+    libssl-dev \
+    libusb-1.0-0-dev \
+    pkg-config \
+    libgtk-3-dev \
+    libglfw3-dev \
+    libgl1-mesa-dev \
+    libglu1-mesa-dev \    
+    curl \
+    python3 \
+    python3-dev \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Download sources
+WORKDIR /usr/src
+RUN curl https://codeload.github.com/IntelRealSense/librealsense/tar.gz/refs/tags/v$LIBRS_VERSION -o librealsense.tar.gz 
+RUN tar -zxf librealsense.tar.gz \
+    && rm librealsense.tar.gz 
+RUN ln -s /usr/src/librealsense-$LIBRS_VERSION /usr/src/librealsense
+
+# Build and install
+RUN cd /usr/src/librealsense \
+    && mkdir build && cd build \
+    && cmake \
+    -DCMAKE_C_FLAGS_RELEASE="${CMAKE_C_FLAGS_RELEASE} -s" \
+    -DCMAKE_CXX_FLAGS_RELEASE="${CMAKE_CXX_FLAGS_RELEASE} -s" \
+    -DCMAKE_INSTALL_PREFIX=/opt/librealsense \    
+    -DBUILD_GRAPHICAL_EXAMPLES=OFF \
+    -DBUILD_PYTHON_BINDINGS:bool=true \
+    -DCMAKE_BUILD_TYPE=Release ../ \
+    && make -j$(($(nproc)-1)) all \
+    && make install 
+
+######################################
+#   librealsense Base Image Stage    #
+######################################
+FROM ${BASE_IMAGE} as librealsense
+
+# Copy binaries from builder stage
+COPY --from=librealsense-builder /opt/librealsense /usr/local/
+COPY --from=librealsense-builder /usr/lib/python3/dist-packages/pyrealsense2 /usr/lib/python3/dist-packages/pyrealsense2
+COPY --from=librealsense-builder /usr/src/librealsense/config/99-realsense-libusb.rules /etc/udev/rules.d/
+ENV PYTHONPATH=$PYTHONPATH:/usr/local/lib
+
+# Install dep packages
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \	
+    libusb-1.0-0 \
+    udev \
+    apt-transport-https \
+    ca-certificates \
+    curl \
+    software-properties-common \
+    && rm -rf /var/lib/apt/lists/*
+
+# Shows a list of connected Realsense devices
+CMD [ "rs-enumerate-devices", "--compact" ]

scripts/Docker/build_image.sh

@@ -0,0 +1,14 @@
+#! /bin/sh
+
+# This script builds docker image of the latest librealsense github tag 
+# Get the latest git TAG version
+LIBRS_GIT_TAG=`git describe --abbrev=0 --tags`
+LIBRS_VERSION=${LIBRS_GIT_TAG#"v"}
+
+echo "Building images for librealsense version ${LIBRS_VERSION}"
+docker build \
+        --target librealsense \
+        --build-arg LIBRS_VERSION=$LIBRS_VERSION \
+        --tag librealsense \
+        --tag librealsense --tag librealsense:$LIBRS_GIT_TAG \
+        .

scripts/Docker/build_image_multi_platform.sh

@@ -0,0 +1,28 @@
+#! /bin/sh
+
+# This script builds librealsense for both the x86_64 and arm64 platforms. 
+# See: https://docs.docker.com/buildx/working-with-buildx/
+
+# Get the latest git TAG version
+LIBRS_GIT_TAG=`git describe --abbrev=0 --tags`
+LIBRS_VERSION=${LIBRS_GIT_TAG#"v"}
+
+echo "Building images for librealsense version ${LIBRS_VERSION}"
+
+# Build x86_64 image
+docker buildx \
+    build \
+    --platform linux/amd64 \
+    --target librealsense \
+    --build-arg LIBRS_VERSION=$LIBRS_VERSION \
+    --tag librealsense --tag librealsense:$LIBRS_GIT_TAG \
+    -o type=docker,dest=- . > librealsense-amd64.tar
+
+# Build arm64 image (slow!)
+docker buildx \
+    build \
+    --platform linux/arm64 \
+    --target librealsense \
+    --tag librealsense --tag librealsense:$LIBRS_GIT_TAG \
+    --build-arg LIBRS_VERSION=$LIBRS_VERSION \
+    -o type=docker,dest=- . > librealsense-arm64.tar

scripts/Docker/readme.md

@@ -0,0 +1,97 @@
+# Librealsense Docker
+
+This tutorial aim is to provide instructions for installation and use of Librealsense Docker. 
+Current version of the docker includes the following capabilities:
+- use of librealsense devices
+- use of librealsense API
+- installation of the basic examples for use of librealsense
+
+It does not include (may be enabled later on):
+- graphic examples
+- use of IMU devices
+
+## Pre-Work: Docker Installation
+Install docker in the environemnt using the  following tutorial (adjust for the OS):
+https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-16-04
+
+## Dockerfile description
+- Ubuntu base system (Ubuntu 20.04 by default)
+- **librealsense-builder** stage - builds the binaries and has all the build dependencies 
+- **librealsense** stage -  contains only the built binaries and the required runtime dependencies (~60MB)
+- Support for Python bindings (python not included) and networking
+- Binaries are stripped from debug symbols during build stage to minimize image size
+- Support scripts for building and running the image are also included
+- Next steps - TODO: python version, openGL, self info to be printed
+
+# Getting librealsense docker - pre-built
+
+In order to use the built container by our latest Dockerfile, run the command:
+```
+docker pull librealsense/librealsense
+```
+This will pull librealsense docker saved in [Docker Hub](https://hub.docker.com/).
+
+Please pay attention that librealsense Docker is available only for x86 at this stage.
+
+## Running the Container
+Before running the container, make sure that when running the command: `docker images`, the docker librealsense/librealsense appears.
+Then, the container can be ran by one of the following ways:
+
+Remark: In each of the alternative ways, the aim of the lines: 
+    ```
+        --device-cgroup-rule "c 81:* rmw" \
+        --device-cgroup-rule "c 189:* rmw" \
+    ```
+    is to grant access for the docker to the USB and UVC resources of the host PC (needed to use realsense devices).
+
+- ### Default Command
+    Running the container with default command:
+    ```
+    docker run -it --rm \
+        -v /dev:/dev \
+        --device-cgroup-rule "c 81:* rmw" \
+        --device-cgroup-rule "c 189:* rmw" \
+        librealsense/librealsense
+    ```
+
+    The default command that will run is: `rs-enumerate-devices --compact`
+
+- ### Custom Command
+    In order to run some arbitrary command (run of the rs-depth demo in the following example), one can run for example:
+    ```
+    docker run -it --rm \
+        -v /dev:/dev \
+        --device-cgroup-rule "c 81:* rmw" \
+        --device-cgroup-rule "c 189:* rmw" \
+        librealsense/librealsense rs-depth
+    ```
+    Then, the realsense depth will be displayed as in the following video:
+    ![](LRS_Docker_Depth_example.gif)
+
+
+
+- ### Running shell
+    Use the following command in order to interact with the Docker via shell interface:
+    ```
+    docker run -it --rm \
+        -v /dev:/dev \
+        --device-cgroup-rule "c 81:* rmw" \
+        --device-cgroup-rule "c 189:* rmw" \
+        librealsense/librealsense /bin/bash
+    ```
+
+# Building librealsense docker image
+
+The librealsense's docker image can be built locally using the [Dockerfile](Dockerfile). 
+This is done by running the [image building script](build_image.sh) - run it in the following way:
+```
+./build_image.sh
+```
+
+Then, running the container is done as described [above](#Running-the-Container) .
+
+
+
+
+
+

scripts/Docker/run_image.sh

@@ -0,0 +1,10 @@
+#! /bin/sh
+
+# By using --device-cgroup-rule flag we grant the docker continer permissions -
+# to the camera and usb endpoints of the machine.
+# It also mounts the /dev directory of the host platform on the contianer 
+docker run -it --rm \
+    -v /dev:/dev \
+    --device-cgroup-rule "c 81:* rmw" \
+    --device-cgroup-rule "c 189:* rmw" \
+    librealsense